D.2 Administering Your Subversion Server

Larger companies 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.

D.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. Although NetIQ 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 the Apache Subversion Mailing Lists.

D.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, no matter which 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 box 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 are 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 need specific configuration to support it. Many firewall administrators are wary of changing their configuration.

You should check with all organizations 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. WevDAV 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 NetIQ 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 D-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

D.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 usernames 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 D-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 need to use the Apache HTTP server configuration to specify your realm. More information about configuring this information can be found at the Apache 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, Authorization and Access Control 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, NetIQ eDirectory, and many more. NetIQ 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 you configure 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.

D.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 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 D-3 Authenticating to Version Control

D.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 mod_dav_svn Configuration Directives.

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.

D.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, 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 D-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.

D.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 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 about the dump and hotcopy commands, including examples, see svnadmin dump and svnadmin hotcopy.