Migrating from CollabNet Subversion Edge to VisualSVN Server

Applies to: VisualSVN Server 5.3 and later

Migrating from CollabNet® Subversion Edge to VisualSVN Server is typically straightforward. In most cases, the migration can be done transparently to end users. This article aims to provide step-by-step instructions for a smooth migration.

Summary

• Step 1: Preparing for migration. Before you begin the migration, there are things that are better to decide on and do in advance, so that you do not spend extra time on these during the actual migration and the migration goes faster.
• Step 2: Installing VisualSVN Server. You need to install VisualSVN Server by running its installer and following the steps in the installation wizard.
• Step 3: Configuring VisualSVN Server. At this point you need to perform the initial configuration of your new VisualSVN Server installation. If required, you can reproduce the configuration of your current Subversion Edge installation.
• Step 4: Migrating your repositories to VisualSVN Server. At this point you need to import your repositories into VisualSVN Server. The repositories will be temporarily inaccessible starting from this step.
• Step 5: Updating the DNS records and going live in production. At this point you can update the DNS records so that the URLs of your Subversion repositories remain unchanged. Then the server should be ready to go live in production.
• Step 6: Further improvements to the server setup. At this point your new VisualSVN Server installation should be live in production. It is time to take final configuration steps and enable the features such as scheduled repository verification, scheduled backups, etc.

Step 1: Preparing for migration

Make sure to address the points below when preparing to migrate your repositories from Subversion Edge to VisualSVN Server. These points can be addressed in any preferred order.

Step 1.1: Plan the downtime

The migration procedure requires you to stop the services of your current Subversion Edge installation before importing repositories into VisualSVN Server. The services have to remain in the stopped state at all times while the repository migration is in progress. Plan accordingly, to eliminate impact on users. It would be a good idea to copy the repositories overnight or on a weekend.

Step 1.2: Ensure that server migration is transparent to end users

The migration is typically transparent to end users and does not require any special steps on the user's end. In particular, users having uncommitted changes don't have to commit them prior to the migration and can continue working as normal when the migration completes.

However, note that if the URL to your server and repositories changes during the migration process, users will need to relocate their working copies to the new URL or checkout new working copies.

Take into account the following aspects:

• It is recommended that the URL to repositories remain unchanged. Upon the completion of the migration process, change the DNS records for the old server's DNS name to point to the new server computer. See Step 5.1 of the procedure for more information.
• If you cannot keep the old server's URL, users will need to relocate their working copies or checkout new ones. Read the following pages for more information:
  • SVNBook | svn relocate.
  • TortoiseSVN Manual | Relocating a working copy.

Step 1.3: Verify repositories

Verify repositories for corruptions prior to migration. This is a mandatory diagnostic measure aimed to keep unhealthy repositories away from your future environment.

Run the svnadmin verify command-line utility to check the data integrity of your repositories. The svnadmin verify utility requires that you pass the path to each repository you want to verify. So you either need to repeat the command against all of your repositories one by one or script this procedure.

On Windows the commands should look as follows:

svnadmin verify C:\csvn\data\repositories\MyRepo

svnadmin verify C:\csvn\data\repositories\MyAnotherRepo

On Linux the commands should look as follows:

svnadmin verify /csvn/data/repositories/MyRepo

svnadmin verify /csvn/data/repositories/MyAnotherRepo

Although the repository may show no user-visible symptoms of being corrupt, its integrity may still be internally compromised, and problems caused by this will surface in the future. Therefore, it is crucial to verify the repositories before the migration, after the migration and continue to do so on a regular basis in the future.

In the best scenario, all the migrated repositories should pass the verification without any errors. And if svnadmin verify discovers any issues, they have to be resolved before proceeding with the rest of the migration procedure. If it's impossible to resolve the issues before the migration, you should note down and track the names of corrupt repositories and the details of errors svnadmin verify shows.

Step 1.4: If required, prepare to adjust and move repository hook scripts

If your repositories have any hook scripts configured, you need to ensure that these hooks will also work on the new server. In order to do so, verify that your current scripts are not linked to your old environment (i.e., do not contain absolute paths, non-default environment variables, or run third-party programs). Otherwise, plan ahead on adjusting hooks and installing all the necessary third-party programs on the new server.

In Subversion Edge, you can check the hook scripts in the admin web console. The hook scripts of a repository are listed in the properties of a particular repository on the 'Hook Scripts' tab. Note that the hook script files with the *.tmpl extensions are unused template files and can be ignored.

See the article KB188: Understanding Subversion repository hooks for more information about hook scripts in VisualSVN Server and for a list of built-in hooks.

Step 1.5: Perform a partial test migration in a testing environment

It is recommended to try out the migration procedure first by migrating only a portion of your Subversion repositories in a pre-production (testing) environment. Use this test migration to identify any potential roadblocks or issues that you need to solve before or during your final migration.

Step 2: Installing VisualSVN Server

Once you are done with preparation steps, it is time to start installing your new VisualSVN Server instance.

You need to download the installer package from the main download page, run it and follow the steps in the installation wizard. For more details, see the section titled Installing VisualSVN Server in the Getting Started guide.

Step 3: Configuring VisualSVN Server

Step 3.1: Performing initial configuration

Once you have installed VisualSVN Server, see the section titled Performing Initial Configuration in the Getting Started guide, which covers all the steps necessary for deploying a new installation of VisualSVN Server. For now, please skip importing the repositories and setting user permissions, as this will be covered below in Step 4 of the migration procedure.

When configuring VisualSVN Server, pay attention to the following options:

• Configure the URL prefix. By default, the URL prefix in both VisualSVN Server and Subversion Edge is /svn, so that repository URLs look as follows: https://svn.contoso.com/svn/MyRepo

  But if your old Subversion Edge installation is configured to use a non-default URL prefix, then you can reflect this setting in VisualSVN Server.

  Tip

  The URL prefix in VisualSVN Server may contain only alphabetical, numeric, dash and underscore characters. It cannot contain special characters or have multiple path components separated by slashes. But Subversion Edge allows the use of special characters and slashes in the 'Context Path' option, so you may be unable to reflect the setting in VisualSVN Server.

  In Subversion Edge, the option is named Context Path and is available in Administration | Server Settings | Advanced Settings.

  In VisualSVN Server, the option is available on the Network tab in VisualSVN Server Properties. See the article KB191: Understanding VisualSVN Server network settings for more information.

• Configure the authentication mode. You need to decide which authentication mode you are going to use with VisualSVN Server and enable it on the Authentication tab in VisualSVN Server Properties.

  Local authentication in Subversion Edge corresponds to the Subversion authentication mode in VisualSVN Server. However, if you intend to operate your new server within an Active Directory environment, VisualSVN Server also provides a dedicated Windows authentication mode. See the article KB182: VisualSVN Server authentication modes for more information.

Step 4: Migrating your repositories into VisualSVN Server

Step 4.1: Stopping services

You need to stop both the Subversion Edge and VisualSVN Server services before proceeding. The repositories will be temporarily inaccessible starting from this point. This is a mandatory step to secure your repositories from being changed during the migration.

To stop the Subversion Edge services:

1. Open the Subversion Edge web management console.
2. Click Administration and Status.
3. Click the red Stop button to stop the services.

To stop the VisualSVN Server services:

1. Start the VisualSVN Server Manager console.
2. Click the Stop button on the toolbar.

Step 4.2: Importing repositories

The next step is to import your repositories into VisualSVN Server. This process is pretty simple, but copying may take a considerable amount of time, during which the repositories will be inaccessible.

See the article KB10: Importing Repositories into VisualSVN Server for instructions (consider the section Copy repository from another location).

By default, Subversion Edge stores the repositories in the following directory:

• On Windows: C:\csvn\data\repositories
• On Linux: /csvn/data/repositories

When unsure about the location of your repositories, you can find it by checking the Repository Directory option in the Subversion Edge web management console (Administration | Server Settings).

Step 4.3: Verifying repositories on the new server computer

Once the repositories are imported, verify them in VisualSVN Server. This step ensures that your repositories were copied correctly, i.e. were not corrupted during the migration process.

Perform verification in one of the following ways:

• Create and run the Verify Repository job.
• Select the repository in the VisualSVN Server Manager console and click Action | All Tasks | Verify repository on the toolbar menu.
• Run the Test-SvnRepository PowerShell cmdlet.

Step 4.4: Migrating user credentials (Subversion authentication mode only)

This step is optional and is only relevant if you are going to use the Subversion authentication mode with VisualSVN Server. You should skip this step if you are going to use Windows authentication in an Active Directory environment.

If you are going to use the standalone Subversion authentication mode, you have an option of keeping your existing list of user credentials. For this to happen, you need to copy the file svn_auth_file into VisualSVN Server's repositories root directory.

The files svn_auth_file and htpasswd are used in Subversion Edge and VisualSVN Server respectively to store the list of usernames and password hashes for the standalone Subversion authentication mode (aka Basic authentication). These files don't contain the actual passwords, but only their hashes.

Alternatively, you can skip this step and create user accounts through the VisualSVN Server Manager console or using the New-SvnLocalUser PowerShell cmdlet.

By default, the path of the svn_auth_file of Subversion Edge is as follows:

• On Windows: C:\csvn\data\conf\svn_auth_file
• On Linux: /csvn/data/repositories\svn_auth_file

The file needs to be copied into the repositories root directory of VisualSVN Server and renamed as follows:

• C:\Repositories\htpasswd

You can find out the actual path to your repositories root directory on the Storage tab in VisualSVN Server Properties.

Note that the file svn_auth_file has to be renamed to htpasswd as shown above. If the file htpasswd is already present in the repositories root directory, you can first rename it into htpasswd-old.

Step 4.5: Migrating group accounts (Subversion authentication mode only)

This step is optional and is only relevant if you are going to use the Subversion authentication mode with VisualSVN Server. You should skip this step if you are going to use Windows authentication in an Active Directory environment.

In Subversion Edge, the list of groups and their members is defined in the same file as path-based access rules. Follow these steps to view the list of groups:

1. Open the Subversion Edge web management console.
2. Click Repositories and Access Rules.

These groups can be configured in VisualSVN Server from scratch using the VisualSVN Server Manager console or using the New-SvnLocalGroup and Add-SvnLocalGroupMember PowerShell cmdlets. See Appendix A: Example of group accounts migration for additional information.

Step 4.6: Configuring user access permissions

User permissions in the Subversion repositories have to be configured from scratch after importing the repositories into VisualSVN Server.

You can check the list of access rules configured in Subversion Edge and add the same permissions in VisualSVN Server. See Appendix B. Example of path-based access rules migration for additional information.

VisualSVN Server Manager console provides an intuitive graphical interface for permission management. For automation or batch processing of access rules, check *-SvnAccessRule PowerShell cmdlets such as Add-SvnAccessRule. See Getting Started | Configuring User Permissions for more information.

To view the path-based access rules in Subversion Edge, open the 'Access Rules' list in the web management console:

1. Open the Subversion Edge web management console.
2. Click Repositories and Access Rules.
3. The list under 'Repository Access Rules' shows the actual path-based access rules configured in your Subversion Edge server installation.

Step 4.7: Configuring hook scripts

This step is optional and is relevant only if your repositories have hook scripts configured. You can skip this step if the repositories don't use any hook scripts.

If your old Subversion server had any hook scripts set up for its repositories, you should have prepared to move them (as outlined in Step 1.4). If any of your hook scripts rely on third-party tools to work properly, ensure that those tools are installed and configured on the server. Step 4.8 below presents an opportunity to make a test run of your VisualSVN Server installation, ensuring that the hook scripts work correctly.

Please see the article KB188: Understanding Subversion repository hooks for more information.

Step 4.8: Making a preliminary test of your new server installation

After configuring your new server and migrating the repositories, confirm their accessibility by Subversion clients and web browsers, and verify the functionality of any migrated or added hook scripts.

To start the VisualSVN Server services:

1. Start the VisualSVN Server Manager console.
2. Click the Start button on the toolbar.

The VisualSVN Server services will start and the repositories become available over HTTP(S).

To access repositories hosted on the new server, make sure to use the correct URL. You can find the repository URL using VisualSVN Server Manager console:

1. Start the VisualSVN Server Manager console.
2. Expand the Repositories node.
3. Right-click a repository or repository path and click Copy URL to Clipboard.

You can use this URL in a web browser and your Subversion client to test drive your new server installation.

Once testing is complete, stop the VisualSVN server services again:

1. Start the VisualSVN Server Manager console.
2. Click the Stop button on the toolbar.

The VisualSVN Server services will stop and the repositories won't be available over HTTP(S) until you start the services again.

Step 5: Updating the DNS records and going live in production

Step 5.1: Configuring DNS to point to the new server

If you installed VisualSVN Server on a computer different from the old Subversion Edge instance, consider updating the DNS records so that they point to the new server computer. This ensures that the URL remains the same for the users. Also edit the server name on the Network tab in VisualSVN Server Properties. Reach out to your system administrator for assistance if necessary.

If you would like to keep the original URL of your repositories, make sure that there is a DNS record that points the old server's name to the new server computer (preferably using a CNAME DNS record). Once DNS settings are configured, your repositories become available at the specified URL.

Please see the article KB224: Configuring a custom DNS name for VisualSVN Server in Active Directory for detailed guidance on how to create a new DNS record. Although the article shows how to configure the DNS record in an Active Directory environment, you can still use it as reference if your VisualSVN Server installation isn't deployed in a domain environment.

Step 5.2: Going live in production

After completing all the previous steps, your new VisualSVN Server installation should be ready to go live in production.

Please ensure that the services of your new VisualSVN Server installations are running. Follow these steps to start the VisualSVN Server services:

1. Start the VisualSVN Server Manager console.
2. Click the Start button on the toolbar.

The VisualSVN Server services will start and the repositories become available over HTTP(S).

Your new VisualSVN Server installation should be up and running, and the repositories should be available to end users at this point. From now on, all further work with the repositories should be performed through VisualSVN Server. Your old Subversion Edge installation can be decommissioned.

Step 6: Further improvements to the server setup

It is recommended to go through the list below and perform the final configuration steps.

Schedule Repository Backup

This is the most important feature to be reconfigured after migration. When deploying VisualSVN Server, you need to add a scheduled backup job to ensure that your repositories are properly backed up. Read the KB106: Getting started with Backup and Restore article for setup instructions.

Schedule Repository Verification

Verifying your repositories on a regular basis is vital for early detection of repository corruptions caused by disk failures. Read the KB115: Getting started with repository verification jobs article for setup instructions.

Upgrade the Subversion clients

VisualSVN Server is linked with the most up to date version of Apache Subversion and other components. To benefit from all the improvements, it is recommended to also upgrade your users' Subversion clients to the latest available version.

Upgrade the filesystem format of your repositories

It is strongly recommended to upgrade your repositories to the latest filesystem format in order to benefit from performance improvements implemented in the latest VisualSVN Server and Apache Subversion releases. Read the article KB142: Upgrading the filesystem format of a repository for instructions.

Optional: Enable Repository Management Delegation

This feature helps you delegate user permission management duties by assigning repository supervisors. Read the KB62: Getting started with Repository Management Delegation article for setup instructions.

Optional: Enable Remote Server Administration

VisualSVN Server Manager console is implemented as a standard Microsoft Management Console (MMC) snap-in and allows you to manage multiple Subversion servers remotely from a single console. Read the KB25: Configuring Remote Administration article for setup instructions.

Appendix A: Example of group accounts migration

This step is optional and is only relevant if you are going to use the Subversion authentication mode with VisualSVN Server. You should skip this step if you are going to use Windows authentication in an Active Directory environment.

In the majority of cases, it is sufficient to configure the groups via the VisualSVN Server Manager (admin GUI console). But this example should help when your Subversion Edge has a long and complex list of groups that are hard or time-consuming for the administrator to create through the graphical console.

The syntax of the groups definitions list of Subversion Edge is described in SVNBook | Path-Based Authorization.

Groups in Subversion Edge

To view the user groups in Subversion Edge, open the 'Access Rules' list in the web management console:

1. Open the Subversion Edge web management console.
2. Click Repositories and Access Rules.
3. Groups are defined in the section that starts with [groups].

   [groups]
   Managers = user1, user2
   Engineers = engineer1, engineer2
   AllGroups = @Managers, @Engineers
   

In the example above, the configuration has three groups: Managers, Engineers and AllGroups:

• Users user1 and user2 are members of group Managers.
• Users engineer1 and engineer2 are members of group Engineers.
• Groups Managers and Engineers are members of group AllGroups. Therefore all users who belong to groups Managers and Engineers also belong to group AllGroups.

Migrating the groups into VisualSVN Server

Migrating these groups requires an administrator to first migrate or create the user accounts. Then you can create the groups and add members with the following PowerShell commands:

New-SvnLocalGroup -Name Managers
Add-SvnLocalGroupMember Managers (Get-SvnLocalUser user1,user2)
New-SvnLocalGroup -Name Engineers
Add-SvnLocalGroupMember Engineers (Get-SvnLocalUser engineer1,engineer2)
New-SvnLocalGroup -Name AllGroups
Add-SvnLocalGroupMember AllGroups (Get-SvnLocalGroup Managers,Engineers)

Appendix B: Example of path-based access rules migration

In the majority of cases, it is sufficient to configure the access rules via the VisualSVN Server Manager (admin GUI console). But this example should help when your Subversion Edge has a long and complex list of granular permissions that are hard or time-consuming for the administrator to configure through the graphical console.

The syntax of the Repository Access Rules list of Subversion Edge is described in SVNBook | Path-Based Authorization.

Access rules in Subversion Edge

To view the path-based access rules in Subversion Edge, open the 'Access Rules' list in the web management console:

1. Open the Subversion Edge web management console.
2. Click Repositories and Access Rules.
3. The list under 'Repository Access Rules' shows the actual path-based access rules configured in your Subversion Edge server installation.

   [/]
   * =
   
   [calc:/trunk]
   @developers = r
   
   [calc:/branches/calc/bug-142]
   harry = rw
   sally = r
   
   [calc:/branches/calc/bug-142/secret]
   harry =
   

In the example above, the configuration has five access rules. The first one is for the topmost server-wide level [/]. And the rest of access rules are configured on paths within the repository named calc.

Migrating the access rules into VisualSVN Server

Migrating these access rules requires you to run five PowerShell commands:

Add-SvnAccessRule -Global -AccountName Everyone -Access NoAccess
Add-SvnAccessRule -Repository calc -Path /trunk -AccountName developers -Access ReadOnly
Add-SvnAccessRule -Repository calc -Path /branches/calc/bug-142 -AccountName harry -Access ReadWrite
Add-SvnAccessRule -Repository calc -Path /branches/calc/bug-142 -AccountName sally -Access ReadOnly
Add-SvnAccessRule -Repository calc -Path /branches/calc/bug-142/secret -AccountName harry -Access NoAccess