E.0 Version Control with Subversion and Identity Manager Designer

This appendix is intended for people using Identity Manager Designer and Subversion. Identity Manager Designer includes complete documentation covering how to use version control. This appendix gives more background on Subversion and indicates why you should make certain decisions. The Designer documentation tells you which protocols are supported. This paper tells you why you should choose one over the others.

There are many books available on administering a Subversion server and working with Subversion. I recommend Version Control With Subversion. It is available without charge at O’Reilly Media. This is an excellent reference book for Subversion. Many topics in the book are touched upon in this paper, and this paper references specific sections of the book.

E.1 Understanding Subversion

Subversion is a version control system. Version control systems let you manage and create multiple revisions of your project and documents. They also allow you to share those revisions among a team of people.

E.1.1 How Revisions Work In Subversion

Revisions are a the heart of the Subversion functionality. A revision is a number that marks a specific set of changes made to a set of files. A single revision number can cover changes made to multiple files, but all of those files must be in the same repository.

Subversion uses a single revision number for the entire repository. This revision number is incremented every time any change is made to the Subversion server. For example, if you import a project at revision 100 and then create an Identity Vault and commit (revision 101), create a driver and commit (revision 102), and create a policy and commit, you are at revision 103. If you have multiple projects in the same repository, then every change made to any project increments the revision number for the whole server.

Although revision numbers are created for the entire server, different objects in your project can have different revision numbers. For example, suppose you start with revision 100 and create a policy and commit it; then create a mapping table resource and commit that version. The project will be at revision 100, the policy will be at revision 101, and the mapping table resource will be at revision 102. You can see the current revision of a specific object by using the Revision History or Properties page. The Revision History page indicates the specific object revision with a yellow arrow. In this example, the yellow arrow points to revision 100 for the project even though you see revision 101 and 102.

Subversion is meant to work in a team environment. In a team environment, there could be someone else editing the project at the same time as you. Let's look at an example:

Alice imports a project at revision 100 to her local workspace.
Bob imports the same project, also at revision 100, to his local workspace.
Alice adds a new policy and commits, which creates revision 101.
Bob adds a different new policy and commits, which creates revision 102

At this point Alice’s project is at revision 100, her policy is at revision 101, and the latest revision on the server is revision 102. If Alice wants to see Bob’s policy, she needs to update her project so she has revision 102.

Figure E-1 Viewing Changes Through the Revision History

Revisions are a useful way to track the versions of your project. Revisions can help you get projects back from the history and make sure that two users have the same version of a project loaded.

E.1.2 Understanding Atomic Commits

Atomic commits are a major feature of Subversion. The atomic commits treat the commit operation as a single event that either completely succeeds or fails gracefully. That means all of your changes are committed to the server or none of them are. Let's look at an example. Alice and Bob are working together on a project. Alice makes changes to multiple policies and entitlements that are all interdependent. While Alice is in the process of committing this change, her network connection goes down. Before Alice can connect to the server again, Bob does an update. Subversion ensures that Bob does not get a partial update from Alice. Because Alice had a problem during her commit, Subversion makes sure that none of the files are changed on the server. Alice can then perform the commit after her network connection is restored.

Atomic commits are a very powerful tool and an excellent way to avoid broken projects. Atomic commits are always available within Identity Manager Designer and Subversion. You don't need to do anything special to enable them.

E.1.3 Where Subversion Stores the Project Data

When you commit a project to Subversion, the project is stored in the Subversion repository. The Subversion repository is an based on an internal database Subversion uses to store files. Subversion stores a separate file containing the specific changes made in each revision using the revision number as the filename.

These files are combined to maintain the concatenation of all of the changes made in your repository and the history of those changes. These files are iterative in nature and contain only the changes made for that specific revision. You can access these files in the db/revs directory of your Subversion repository.

Beyond that one requirement, there are no firm rules about setting up your projects. Here are some guidelines:

It is a good practice to place a project in a directory of the same name. For example, the project called project1 would go into a folder such as trunk/projects/project1.
Most repositories have a “sandbox” area. Users new to version control can experiment in this area without worrying about corrupting existing projects.
It is a good practice to organize groups of projects. You can group projects by user, team, or company. The key is that having a large number of projects at the same level can be difficult to navigate.

E.1.4 Moving an Existing Project

Identity Manager Designer does not provide support for moving a committed project from one place on your Subversion server to another. However, you can do this with the Subversion command line:

Make sure the whole team commits all of their local changes.
Have all team members delete their local projects.
Use the Subversion move command to move the project location.
Have each team member import the project from the new location.

The Subversion move command is very simple. You just specify the current location of the project and the new location you want to move it to. For example, if your project is located at trunk/project1 and you want to move it to trunk/myprojects/project1, use the following command:

svn mv -m "<your comment for the move>" http://myserver/trunk/project1 http://myserver/trunk/myprojects/project1

Subversion moves the project to the new location and maintains all of the files and history.

E.2 Administering Your Subversion Server

Larger companies will most likely have a Subversion server administrator. Smaller companies might require you to install the Subversion server yourself. You can also choose to install Subversion on your own machine for easy backups. Either way, it is a good idea to know how the server should be configured and administered.

E.2.1 Server Specifications

The platform where you run Identity Manager Designer and the platform where you run the Subversion server are completely independent. Identity Manager Designer includes a Subversion client and is supported on any platform where Identity Manager Designer is supported.

Subversion provides official builds for the following platforms:

Red Hat Linux
Debian GNU/Linux
FreeBSD
OpenBSD
NetBSD
Solaris
Mac OS X
Windows NT, 2000, XP, and 2003
HP-UX
AIX
IBM i5/OS (OS/400)

Subversion also works very well on SUSE Linux, but an official SUSE build is not available from the official Subversion site. Although Novell strongly encourages you to run on SUSE Linux, the Subversion server works well on all of the platforms. The platform you choose might depend on the IT organization you are working with, existing infrastructure, or just personal preference.

Subversion is a lightweight product and doesn't require a very powerful machine. The specific requirements depend on many factors, such as the number of users, the number of projects, and the other software running on that system. There is a discussion thread with some specific recommendations you can find at Subversion Mailing List.

E.2.2 Network Protocols

Subversion supports direct file access, and the SVN, HTTP, HTTPS, and SVN+SSH network protocols. These protocols define how Designer communicates with the Subversion server. The server must be configured to support a set of specific protocols. You specify the protocol you are using in the first part of the URL you use to connect to your version control server.

The protocol that you are using is transparent while you use Designer. Everything works basically the same whichever protocol you use. However, the choice of protocol has significant impact on the network traffic, security, and speed of your interactions with Subversion. Choosing the protocol is an important decision.

Direct File Access

Direct file access is not actually a network protocol. You can simply point Designer at a repository on your hard driver and access it directly. This is the easiest option to set up because it doesn’t even require the Subversion server to be running. The version control import dialog has an option to browse for your local repository location. This is a good option for single users, experimenting with version control, and giving demonstrations.

The main drawback of direct file access is that it doesn’t support network access for multiple users. Direct file access is not a network protocol; your repository cannot be accessed by other people. As a result, it does not provide good support for authentication schemes. This makes direct file access a poor choice for team environments.

You specify this protocol by connecting to your server with a URL that looks like this:

C:\subversion\myrepository

/home/<my username>/subversion/myrepository

SVN

SVN is a Subversion-specific protocol. This is the protocol that is used when you run the Subversion server without the Apache HTTP Server. Just follow the Subversion server setup instructions in the Identity Manager Designer documentation and you will be using this protocol. The SVN protocol supports networking and works well with small teams. It supports password file authentication as well as path-based authentication.

The SVN protocol does not support any type of encryption. This means that all information sent between Identity Manager Designer and the Subversion server is in clear text and could potentially be seen by a third party. Another concern with the SVN protocol is accessibility through firewalls. SVN is a specialized protocol and most firewalls will need specific configuration to support it. Many firewall administrators are wary of changing their configuration.

You should check with all companies involved before choosing this option. If you do need to configure a firewall to allow the SVN protocol, you must allow connections on TCP port 3690. In addition, the SVN protocol is not supported by most proxy servers.

The SVN protocol is a good choice for small teams where everyone works together in the same company. It is fast and easy to configure. You specify this protocol by connecting to your server with a URL that looks like this:

svn://mysubversionserver/myrepository

svn://localhost

HTTP

Subversion supports the use of HTTP by using a protocol called WebDAV. This protocol allows Designer to access Subversion by using the same protocols that Web browsers use to access the Internet. The Subversion server also requires the Apache HTTP server to support the HTTP protocol. This requires a little more server configuration, but it isn’t too difficult. Using the Apache HTTP server also allows many more authentication options.

The main advantage of HTTP is that it works with existing firewalls and proxy servers. This makes HTTP a good choice when working with multiple companies, or working inside corporate networks. HTTP does not support encryption between the Subversion server and Identity Manager Designer. If you need to protect your data, then you should choose a different protocol. You specify this protocol by connecting to your server with a URL that looks like this:

http://subversion.mycompany.com/myrepository

HTTPS

HTTPS works very similarly to HTTP, with the addition of data encryption between the Subversion server and Identity Manager Designer. HTTPS uses the SSL (Secure Socket Layer) encryption protocol to make sure that third parties cannot read the communications between Identity Manager Designer and the Subversion server. HTTPS is slightly slower, but in practice the difference is negligible. HTTPS is a good choice for corporate environments concerned about securing their data. HTTPS is the protocol Novell developers use when working on the Identity Manager Designer source code.

The main drawback to HTTPS is that it can be difficult to configure. SSL requires a signing certificate that is granted by a certificate authority like Verisign.com. These certificates must be purchased, and applying for and installing them can be time-consuming. However, most server administrators are familiar with this process and should be able to guide you through it. You specify this protocol by connecting to your server with a URL that looks like this:

https://subversion.mycompany.com/myrepository

SVN+SSH

SSH (Secure Shell Protocol) is most popular on UNIX. Windows does not support SSH without additional software, and the configuration can be very difficult. SSH security is based on public key encryption using X.509 certificates. SSH is a good choice for UNIX environments looking for additional security. SSH requires a change to firewalls because it is not allowed on most corporate configurations. SSH uses TCP and UDP over port 22. You specify this protocol by connecting to your server with and URL that looks like this:

svn+ssh://subversion.mycompany.com/myrepository

Protocol Comparison

Table E-1 Protocol Comparison

Protocol	Pros	Cons	Port
Direct File Access	Really easy to set up, great for single developers.	Doesn’t support team environments.	None
SVN	Easy setup and good network support.	Doesn’t support encryption, doesn’t support complex authentication, and has trouble with firewalls.	TCP 3690
HTTP	Good network support, works well with firewalls, and supports complex authentication.	Requires the Apache HTTP server and is not a good choice for running the Subversion server locally.	TCP 80
HTTPS	Good network support with good security options. A good choice for larger corporations.	Requires the Apache HTTP server, a certificate from a third party, and more complicated server configuration.	TCP 443
SVN+SSH	Good security in UNIX environments.	Doesn’t support Windows well and can be difficult to configure.	TCP/UDP 22

E.2.3 Authentication Schemes

In addition to deciding which protocols to use, it is important to look at authentication schemes. An authentication scheme defines the way users identify themselves to your Subversion server. This has significant impact on security as well as user management. Authentication schemes can be just a list of user names and passwords in a flat file, or a multiple-server environment requiring special certificates for each client.

Specifying a Realm

Subversion makes use of realms in order to simplify user management. A realm is a string that identifies how your server authenticates its users. This string does not need to be unique to your server. Specifying the same realm in multiple servers indicates that the same username and password can be used in any server using that realm. The realm your server is using shows up when a user is prompted for authentication information in Identity Manager Designer.

Figure E-2 Providing Authentication for the Realm

By default, Subversion generates a unique ID for your realm, such as:

de409a8-8985-4647-ad92-44aef6788420

You can change the realm for your server in the svnserver.conf file located in your repository’s conf directory. If you are using Subversion in conjunction with the Apache HTTP server, you will need to use the Apache HTTP server configuration to specify your realm. More information about configuring this information can be found at the Appache Core Features page.

User Management

Whether you are just a single user or part of a large team, you need to manage the users who are allowed to access your Subversion server.

Flat Password File

The easiest way to manage user access is with a password file. This file specifies a list of users and their passwords. The file looks like this:

[users] alice = alicepassword bob = bobpassword carol = carolpassword dave = davepassword

This option is easy to configure and works well for small teams where security is not a major concern. However, in environments with larger teams, the management of this file quickly becomes unfeasible. In addition, this system is only as secure as the computer it is running on. If someone gains access to your Subversion server, they have access to this passwords file and every user’s password.

Apache HTTP Authentication

If you configure Subversion to run with the Apache HTTP server, you can take advantage of the Apache HTTP server authentication. This mechanism also works with a flat file, but is much more flexible than the Subversion mechanism. This mechanism can manage users and groups, deny access by IP address, and much more. You can find information about this feature at Apache’s Authentication for Apache HTTP Server page.

Apache HTTP Authentication with Third-Party Modules

Apache includes a large variety of third-party authentication modules. These modules support authentication to Windows NT domain controllers, UNIX password systems, Novell eDirectory, and many more. Novell uses a module to authenticate against an eDirectory server for its internal Subversion servers. As of this writing, there are 76 Apache HTTP modules dealing with authentication.

Creating a more complex authentication scheme might seem like a daunting task, but it can pay off in the long run. A good authentication mechanism can be mostly self-sustaining and gives users the opportunity to manage their own accounts. Combining advanced authentication with SSL or SSH provides ample security for a Subversion environment.

Specifying Project-Level Access

There are times when specifying access on a per-server basis is not sufficient. In those cases, you can use project-level access controls. There is support for this in Subversion as well as in the Apache HTTP server. When configuring this option by using the Subversion server, you can create an authorization DB file. The following sample file grants Alice the rights to read and write everything, Bob the write to read everything, Carol the right to read and write project 1 while only reading project 2, and Dave only the rights to read and write project 2.

[/] alice = rw bob = r

[/Project 1] carol = rw

[/Project 2] carol = r dave = rw

You must specify the location of this file by using the authz-db value in the svnserve.conf file in your Subversion repository conf directory. For more information about configuring this option with the Apache HTTP server, consult the documentation for the mod_auth and mod_access packages.

E.2.4 Using Client Certificates

Most security schemes in Subversion use a username and password to provide authentication. This is security based on something your know (your password). If you are especially concerned about security, you can use SSL client certificates. This is based on something you know (your password) and something you have (the certificate).

You can use client certificates with Identity Manager Designer and Subversion, but you must use the Apache HTTP Server. You will need to configure the Apache HTTP server to accept the client certificates. Apache can be configured to use client certificates by using the mod_ldap package. More information about that package can be found at the Apache Module mod_ldap page.

If your Subversion server is configured to use client certificates, you are will be prompted to provide a certificate in Identity Manager Designer. If you already have a Web browser configured to provide the client certificate, you can export the certificate for use with Identity Manager Designer. Tell your browser to export the client certificate and specify the PKCS#12 format. You can then browse and select this certificate when you are prompted by Identity Manager Designer.

Figure E-3 Authenticating to Version Control

E.2.5 Configuring Subversion with Apache HTTP

The Subversion server is a set of libraries. These libraries are accessible with the custom SVN protocol by using the svnserve program. They are also accessible with the HTTP and HTTPS protocols by using the mod_dav_svn module for Apache HTTP server. This is a module that knows how to use the Apache HTTP server to support Subversion functions by using the WebDAV protocol. You can find information about installing and configuring mod_dav_svn at Configuring mod_dav_svn.

The standalone Subversion server is lightweight, easy to configure, and very stable. However, the Subversion server does not support HTTP, HTTPS, and advanced user authentication as well as other key features. The Subversion server is also not meant for large projects with many users. If you need any of the more advanced features, or if you need to support a large user base, you should use the Apache HTTP server. Both the Apache HTTP server and the Subversion server are free software.

E.2.6 Proxy Server Configuration

A proxy server is an application that takes requests and sends them on to other servers. Proxy servers are often used by companies to monitor and filter access to the Internet. Many large companies require all Internet access to be routed through the proxy server. If you are trying to access a Subversion server that is outside of such a network, then you must configure the proxy settings in Identity Manager Designer.

In the main Designer menu, go to Window and then select Preferences. In the Preferences page, select General > Network Connections. This preference page allows you to configure the proxy server settings for Identity Manager Designer. Select the Manual proxy configuration option and supply the proxy settings specified by your network administrator.

Figure E-4 Setting Proxy Server Settings

Most proxy servers support only the HTTP and HTTPS protocols. Some proxy servers support the SVN+SSH protocol and almost none support the SVN protocol.

NOTE:If you use a proxy server, errors can occur occasionally when the proxy server fails to forward a packet. When errors occur, retry the operation. If you continue to have problems, verify that the proxy server is working correctly.

E.2.7 Subversion Server Backup

When you are using version control, the Subversion server acts as a backup mechanism for all your project data. It is vital that you back up the Subversion server frequently. If you do not back up the Subversion repository and your server has a hardware failure, you will lose your project data. Daily backups are essential for active servers.

Subversion provides two tools to help create backups without interruptions of services: dump and hotcopy. The dump command takes your entire repository and sends the contents to standard out. You can also specify revisions to start and stop at. The hotcopy command creates a copy of your Subversion repository, including the database and all other configuration information. You use the output from either of these commands to restore your Subversion repository during disaster recovery.

For more information on the dump and hotcopy commands, including examples, see Dump Command and Hotcopy Command respectively.

E.3 Taking Full Advantage of Version Control

Using version control to simply commit, update, and share projects can be very useful, but if that is all you do you are missing out on some very exciting functionality. Version control can change the way you work. It can enable a truly team-oriented development methodology.

E.3.1 When to Commit and When to Update

Version control is a tool for sharing and backing up your project. You should take full advantage of it. That means committing often and updating frequently. You should learn to be comfortable with committing. The project doesn’t need to be perfect, just make sure you won't impede your teammates.

You should also update frequently to get your teammate's changes. This ensures that you are working with an up-to-date project, and your changes can work with the changes your teammates are making. You also resolve conflicts in a better way. The earlier you can resolve a conflict, the easier it is be to resolve that conflict.

For example, if two individuals are editing the same policy and they work separately for a week, the two versions of the policy will be very different. This makes it very likely that there are conflicts and very likely that those conflicts are difficult to resolve. If those two users update frequently, they would avoid most of the conflicts and make them much easier to resolve.

E.3.2 Comments

Whenever you commit a change to the version control server, you are prompted for a comment. Comments are your chance to describe the change for yourself and for your teammates. Comments can explain why you did something and what you were thinking when you did it.

Good comments should take the form of sentences. They should describe what you did and why you did it. A good comment should give you a good idea of what has changed, but it does not need to describe every change in detail.

Good Comments

Created a new project for work on the new Active Directory drivers for Unilateral Widgets Incorporated.
Added a new AD driver to connect to the second directory and moved policy1 to a library so we can access it from the new driver.
Changed the second rule in policy1 to avoid the potential for an infinite loop when handling more than three users.

Bad Comments

Comments should not be too brief:

Added new policy
New project
Undid Joe’s change

Comments should also not be too specific:

Changed the condition of policy add password rule operation-data to be the following: <and> <if-operation op="equal">add</if-operation> <if-password op="available"/> <if-xpath op="not-true">operation-data</if-xpath> </and>

E.3.3 Creating and Using Tags

A tag is a readable name given to a specific revision. For example, you could tag revision 100 as Release 1.0. Tagging is most useful for identifying significant revisions. If you certify that you are ready to send a project to a customer, that is probably a good time to create a tag. You can then access that tag later if you need to roll back a change. The combination of tagging and the Get from History feature gives you a powerful tool to manage releases and deployments.

E.3.4 Subversion Keyword Substitutions

You can use Subversion keyword substitution to give you more information on selected objects. For example, you can use the Description area to track the revision number, the date and time an object was last submitted to Subversion, and who submitted the last revision in the description of an object. The following example uses a policy.

Select a policy and bring it up in an editor.
In the Policy Description area, add the following keywords:
- $Date$
- $Rev$
- $Author$
Save these changes to the policy.
Check the project into the version control server.
Update the project from the version control server.
Open the policy in an editor and you will see that Subversion has substituted the keywords to show the following:
- $Date: 2008-05-20 11:17:51 -0500 (Tue, 20 May 2008) $
- $Rev: 1513 $
- $Author: tpew $

You need to perform this procedure for each object for which you want to see this type of information. You can add keywords in any place where you can add text, but the object’s Description area is most accessible. The keywords are updated as you or other team members make changes to the object.

E.4 Glossary

Appache HTTP Server. The server that is used in conjunction with the Subversion server to run the HTTP and HTTPS protocols. The Apache HTTP Server is free and open source. More information, including installation instructions, is available at the Apache HTTP Server Project Homepage.

Authentication Scheme. Controls how users are authenticated with your Subversion server. Can be as simple as a flat file or can support many different authentication servers.

Commit. The process of taking your local changes and sending them to the Subversion server. Also called “checking in.”

Import. You import a project from version control to get a project that has already been created and put it on your local machine. After the initial import, you can use the update process to download subsequent changes.

Repository. The place where the Subversion server holds your files. Repositories can support many projects, and many repositories can be supported on the same computer.

Revision. A number identifying a specific set of changes to files in your project and across the Subversion repository. Revisions are visible in the version control history and properties dialogs.

Server Realm. A string that identifies the authentication scheme to be used for that server. Servers with the same realms can use the same set of credentials to support a variation of single sign-on.

Update. Getting the latest changes from the server and applying them to the work area on your local machine.