Subversion is a version control system that has a number of advantages over CVS and is in common use within the CS department. This page describes the process of setting up a repository, sharing the repository with other users, setting up http access, and setting up Software Configuration Management (SCM) using Trac.

This page is not intended to be an in-depth tutorial on using Subversion. It presents some very basic usage information and CS-specific information about setting up Subversion on the CS systems. You are encourage to read the Subversion Book and visit the Subversion Homepage for more detailed information.

Creating the Subversion Repository

The first step in the process is to set up the Subverson (or SVN) repository. Since we are using NFS extensively you can't use the Berkeley DB format for your repository so you need to use fsfs. For example, if you wanted to create a repository named MyProject in the current directory you could run:

svnadmin create --fs-type fsfs MyProject

This will create a directory named MyProject that includes all the files used by Subvesion to manage your repository.

Subversion Access Methods (URLs)

Subversion repositories are accessed using URLs. You can access your repository directly via the filesystem or via https access on the CS web server using URLs of the form. file: or https:. For example, to access the MyProject repository in your home directory via the filesystem, you would use:

file:///u/username/MyProject

To access your repostory via the web server you would use

https://www.cs.indiana.edu/svn/web_repository_name

Note that https access will only work after the required configuration detailed below, which includes setting the web_repository_name to either your username or a project name.

Basic Subversion Use

This is a very quick introduction to a couple basic Subversion operations using a file: URL. You should read the Subversion Book and visit the Subversion Homepage for more details.

Here is how you can check out your repository into a directory named mycopy, create a file, and add it to the repository:

% svn checkout file:///u/username/MyProject mycopy
Checked out revision 0.
% cd mycopy
% echo Hello> newfile
% svn add newfile
A newfile
%

We can then modify this newfile and commit the change back into the repository:

% echo Goodbye>> newfile
% svn commit newfile
-> Add a comment about the change and Save Sending newfile
Transmitting file data .
Committed revision 2.
%

You will notice that the commit put you into an editor (pico by default) to add the comment. You can change the editor used by setting the EDITOR environment variable.

You can use the revert command to restore your local copy. For example, we could modify the newfile and then do a revert (without doing a commit) to get the old version back:

% echo This is messed up>> newfile
% cat newfile
Hello
Goodbye
This is messed up
% svn revert newfile
Reverted 'newfile'
% cat newfile
Hello
Goodbye
%

You could then delete this newfile, commit the change to the repository, and update your local copy with:

% svn delete newfile
D newfile
% svn commit
-> Add comment and save
Deleting newfile
% svn update
At revision 3
%

Sharing the Repository For a Group Project

Once you have your repository in place you may want to collaborate with other users, allowing several members of the development team to make changes. There are two primary ways to do this:

1. Local Filesystem Access - In most cases where you are sharing a repository with a group of users, we recommend that you use Web Access as described in the next section instead of Local Filesystem Access. However, if all of the users on the team have CS accounts and have access to your repository, you can also use standard file: access instead. You just need to ensure that these users have read/write access to your repository directory. You can do this using Access Control Lists (ACLs) and a little helper script named acl_open the sets the proper ACLs. For example, if you wanted to open up your MyProject repository to user janedoe you could just run:

   % acl_open /u/username/MyProject janedoe

   Once this is done, this user can use the same svn URL (file:///u/username/MyProject) that you are using.

   If having shared file: access is sufficient this is the simplest access method.

2. Web Access - The second access method available is https: access via the CS web server. This takes additional steps by the systems staff to configure but allows access by remote users who don't have CS accounts and allows simple remote access.

   In order to use https: access you will need to do the following:

   1. Select an authentication method - There are two authentication methods available but only Basic authentication is supported on the CS server. The two methods are:
      • Basic authentication lets you manage accounts yourself and you can create and remove accounts as needed. This allows you to have complete control over accounts but involves a little additional overhead to set up the account. This is the only supported authentication method.
      • Kerberos authentication lets you grant access to users with existing IU accounts without having to manage passwords. Unfortunately, SVN clients will cache password data in the local filesystem so using Kerberos will result in your IU Network ID password being stored in cleartext in the filesystem which is a security concern. For this reason we do not support Kerberos authentication so you should use Basic authentication.

   2. Create the password file (Basic Authentication Only) - You will need to create a password file that will be used with Basic Authentication. This file just contains usernames and encrypted passwords and can be created using the htpasswd command. The file should be named passwd and be in your top level svn repository directory. For example, you can create the password file (using the -c flag to htpasswd) and add an entry for user "janedoe" by running:

      % htpasswd -c /u/username/MyProject/passwd janedoe

      Once the passwd file is created you can add additional entries using htpasswd without the -c flag:

      % htpasswd /u/username/MyProject/passwd joeblo

      You can use any passwords you want when you run htpasswd but keep in mind that they will be cached in cleartext in a file in your homedir so don't use your normal IU account password. The file is not readable by others but we still recommend that you use a different password.

   3. Create the svn authz file - Once a user is authenticated, access is controlled using an authz file, which needs to be located in the top-level of your repository (/u/username/MyProject/authz in our example). This file lets you specify which users get access to whicih parts of the respository. This is probably best explained by example. Here is a simple example where two users (janedoe and joeblo) both have read-write access and everyone else has no access:

      [groups]
      ALL = janedoe, joeblo
      
      [web_repository_name:/]
      @ALL = rw
      * =
      

      Where you would replace web_repository_name with the name of your repository on the web server. This is typically either your username or a project name and will be assigned when you request web access.

      In the next example, there are two directories in the repository, dir1 and dir2, with janedoe having read-write access to dir1 and joeblo having read-write access to dir2. Jim and Mary have read-only access to both directories and everyone else has no acces.

      [groups]
      PROJ1 = janedoe
      PROJ2 = joeblo
      USERS = jim, mary
      
      [web_repository_name:/dir1]
      @PROJ1 = rw
      @USERS = r
      * =
      
      [web_repository_name:/dir2]
      @PROJ2 = rw
      @USERS = r
      * =
      

   4. Set permissions - In order for https access to work, the apache user must have read-write access to your repository. You can do this with ACLs using the acl_open script. For example you can give the apache user access to MyProject with:

      % acl_open /u/username/MyProject apache

   5. Web server config - Submit a request to the CSG asking to have svn https access configured. In your request please include the path to your svn repository and the web_repository_name you selected above. The access will be configured using Basic authentication.

   6. SVN URL - Once all of this is done you should be able to access your repository using the following URL:

      https://www.cs.indiana.edu/svn/web_repository_name/

      Where web_repository_name will either be your username or a project name and will be assigned when the web server configuration is done.

Setting up Trac

Trac is a very nice Software Configuration Management (SCM) tool you can use with your Subversion repository. Trac provides a variety of features including web-based source browsing, an integrated Wiki, and convenient reporting facilities.

Follow these steps to set up Trac:

1. Setup your SVN Repository - Trac is used to access your Subversion repository. You must first follow the steps above to set up your repository before you continue with these steps. Note that you will also have to set up web access as described in the "Sharing the Repository For a Group Project" section above.

2. Configure CGI use - If you have not already done so, set your account up for CGI usage by running "makecgi". Note that you must have a CS Sharkestra account for this to work. See the CGI FAQ for more information.

3. Configure Trac - You need to initialize trac by running the following command. Please note that you must do this on the cgi server to ensure that you are using the right version of trac and you must use the /nfs/nfs1/... path to your homedir since /u/username will not work:

   % ssh cgi.cs.indiana.edu
   % trac-admin /nfs/nfs1/home/username/MyTrac initenv

   You can use any name for the Trac directory so replace username and MyTrac with your values. When you run trac-admin you will be prompted for several values:

   • Project Name - Type your desired project name
   • Database connection string - Accept the default
   • Repository type - Accept the default (svn)
   • Path to repository - Enter "/nfs/nfs1/home/username/MyProject". This path has to work from the CGI server so a path of the form /u/username/MyProject will not work so you have to use this /nfs/... path.

4. Set up access control - You are going to create a trac cgi script on the cgi server. Anyone with access to this directory will have access to your instance of trac and read-only access to your subversion repository. So, you may want to protect this directory by creating a .htacces file to limit access by hostname, with a password, or by user. In this example, we will create a trac directory and limit access to indiana.edu hosts:

   % mkdir /l/cgi/username/cgi-pub/trac
   % chmod 711 /l/cgi/username/cgi-pub/trac
   % echo deny from all> /l/cgi/username/cgi-pub/trac/.htaccess
   % echo allow from .indiana.edu>> /l/cgi/username/cgi-pub/trac/.htaccess
   % chmod 644 /l/cgi/username/cgi-pub/trac/.htaccess

5. Set up trac.cgi - You will need to set up the trac cgi script in your cgi directory. In this example, we will create the file as:

   /l/cgi/username/cgi-pub/trac/trac.cgi

   You must first make sure that the /l/cgi/username/cgi-pub/trac does not exist. If it does, then move it out of the way or remove it first. Then, run the following to create the cgi script:

   % trac-admin /nfs/nfs1/home/username/MyTrac deploy /l/cgi/username/cgi-pub/trac
   % cp /l/cgi/username/cgi-pub/trac/cgi-bin/trac.cgi /l/cgi/username/cgi-pub/trac/trac.cgi
   % chmod 755 /l/cgi/username/cgi-pub/trac
   % chmod 755 /l/cgi/username/cgi-pub/trac/trac.cgi
   

   You will need to replace MyTrac with the path to the trac directory you created when you ran the trac-admin initenv command. You will need to use this special /nfs/nfs1/... path so it will be accessible from the cgi server and not /u/username.

6. Add the first user - You need to set up an initial user with admin rights:

   trac-admin /u/username/MyTrac permission add username TRAC_ADMIN

   Replace username with your own username in both places. This assumes the admin user will have the same username as you.

7. Set up trac.ini - There is a configuration file named trac.ini in the conf subdirectory of your trac directory. It is beyond the scope of this document to describe how to configure trac but here some minimal changes you are likely to want along with the changes required to allow logins using the same password file you set up for svn access above.
   • [header_logo] - In the header_logo section, you can set up an image to display in the header (src) and set the a project name (alt) to use if there is no logo image.

   • account manager - The AccountManager Plugin provides a convenient interface for managing trac accounts. You can enable this as follows:
     1. Install Plugin - Copy the AccountManager plugin from /l/trac/plugins/ to your trac plugin directory. For example:

        cp /l/trac/plugins/TracAccountManager-0.2.1dev-py2.4.egg /u/username/MyTrac/plugins

     2. Configuration - Make the following additions to your trac.ini file:

        [account-manager]
        password_store = HtPasswdStore
        password_format = htpasswd
        password_file = /nfs/nfs1/home/username/MyProject/passwd
        acct_mgr.api.IAccountChangeListener = username@cs.indiana.edu
        htdigest_realm = TracRealm
        
        [components]
        acct_mgr.htfile.HtPasswdStore = enabled
        acct_mgr.admin.accountmanageradminpage = enabled
        acct_mgr.htfile.htdigeststore = enabled
        acct_mgr.web_ui.accountmodule = enabled
        acct_mgr.web_ui.loginmodule = enabled
        acct_mgr.web_ui.registrationmodule = disabled
        trac.web.auth.loginmodule = disabled
        webadmin.* = enabled
        

        Be sure to change the occurances of username and MyProject to match your situation. Also note that this example disables the Registration Module so users can't create their own accounts. If you want to enable this feature please see the security section below before you doi so you understand the risks.

   • svnauthzadmin - The Svnauthz File Administration Plugin provides a convenient interface for managing svn authz files. You can enable this as follows:
     1. Install Plugin - Copy the SvnAuthzAdmin plugin from /l/trac/plugins/ to your trac plugin directory. For example:

        cp /l/trac/plugins/SvnAuthzAdminPlugin-0.1.2._Moved.to.Trac.0.11_-py2.4.egg /u/username/MyTrac/plugins

     2. Configuration - Make the following additions to the [trac] and [component] sections of your trac.ini file and add the [svnauthzadmin] section:

        [trac]
        ...
        authz_file = /nfs/nfs1/home/username/MyProject/authz
        authz_module_name = username
        ...
        
        [components]
        ...
        svnauthz.* = enabled
        ...
        
        [svnauthzadmin]
        show_all_repos = true
        

        Be sure to change the occurances of username and MyProject to match your situation.

8. Security - It is absolutely critical that you understand the security implications of a default Trac installation and that you take steps to secure your Trac instance. The default setup allows anyone to register and, once registered, have permission to view your SVN repository and, perhaps more importantly, create and modify wiki pages. This latter feature is used by spam-slamming bots to pump all kinds of spam content into your site. To prevent this, you are advised to either limit registration or limit the default access for authenticated users.
   • Restrict Registration - If you don't need users to be able to create their own accounts, then you should turn off the Account Manager registration module. You can do this by adding the following to the [components] section of your trac.ini file.

     [components]
     ...
     acct_mgr.web_ui.RegistrationModule = disabled
     ...
     

     Restrict Access - If you need users to be able to create their own accounts, then you should limit the permissions these authenticated users have. To do this, you can do the following:

     1. Login as the administrative user
     2. Go to the Admin tab
     3. Click on Permissions in the General category
     4. Check the various CREATE and MODIFY actions for "authenticated" users and then click on the "Remove Selected items" button to remove those permissions.

     You can always go in and grant individual users specific permissions but this prevents the account created by the spam bot from slamming content into your wiki.

     Access Trac - At this point you should be able to access trac with the url:

     http://cgi.cs.indiana.edu/~username/trac/trac.cgi

     If you set up your .htaccess to limit http access you may have to use https instead.

     Note that the host cgi.cs.indiana.edu has an SSL certificate that is not trusted by most web browsers. This means you will get dire warnings about the server having an invalid security certificate and you will have to add it as a trusted certificate. See the associated FAQ for instructions on how to prevent these errors.

Final Note

If you have any problems with this or find errors in this page please let us know.

[Return to the FAQ index]