Upgrading from SVN MultiSite 4.2 to a later build of 4.2

Follow this procedure if you're currently using SVN MultiSite 4.2. If you are using a different version of SVN MultiSite you should review this instructions in the chapter 5. Upgrading Subversion MultiSite.

Procedure Overview

This upgrade procedure involves the following steps:

Required Time: the upgrade process may take as little as 20-minutes per server. However, on larger deployments the time required may be longer. It may be worth running through the procedure to see if any of your steps will require extra time.

During most of this process Subversion will be in a read-only state so either complete the upgrade out of development hours and ensure that your developers are aware of the brief Subversion outage.

1. Stop Replication

1.1 Open the Admin Console, on the left-hand menu click Stop Proxy.

nothing goes to plan

1.2 Check that radio button for "Synchronized Stop of all proxies", then click Continue. MultiSite will now wait for any remaining transactions to complete, after which all nodes will stop listening, stopping replication.

2. Export Data

2.1 Open the Admin Console and click on the System tab.

2.2 Click on Export Settings. Note the filename and location, then click on Backup Settings. Settings and user data will be exported to the resulting backup directory, the file that you will need to re-import is called access-control.xml

Using LDAP?
Near the end of the upgrade process you will need to reapply the settings for any LDAP authorities that you are using. You may benefit from making a record of these settings now.

IMPORTANT: When you add the the LDAP auths into 4.2. the Order field for each LDAP auth needs to be exactly the same as the corresponding ldap auths in the MS installation you are upgrading from.

3. Reset

3.1 Perform a reset on all nodes. A reset purges all temporary data which will ensure that all nodes will be in the same state after the upgrade.

Open a terminal and navigate to the <INSTALL>/svn-replicator/bin/ directory. Run reset, like so:

[root@localhost bin]# perl reset

      ===================== WARNING ========================
      This is an irreversible operation. It will delete the
      transaction logs for this replicator. You *must* run
      the reset command on all the replicators to ensure
      there is no lingering state.

Are you sure you want to reset the replicator transaction log - Y|N ? [N] : Y
Shutdown in progress .......May 20, 2013 11:01:17 AM org.nirala.trace.Logger info
INFO: Invoked from WANdisco installation at: /home/wandisco/svn-replicator
May 20, 2013 11:01:17 AM org.nirala.trace.Logger info
INFO: forceSyncPrevayler set to : false
Sending kill signal to 20851...
Shutdown complete

Reset done.

Repeat this for all nodes.

4. Back Up MultiSite Directory

4.1 Create an archive of the svn-replicator directory.

5. Run the upgrader script

** Alert! ** Alert
Don't forget to repeat these steps for each node.

6. Run the conversion script

In 4.2 Build: 3256 we introduced the ability to run with simultaneous LDAP and internal authentication. Adding this feature required a small change to the Access Control database with the addition of a 'user type' field that recorded whether a user was added internally or supplied from an LDAP service.

6.1 In order to import data from an earlier version of MultiSite you will need to first copy the backup (backup.xml or access-control.xml) file that you created in step 2 into the utils directory (<:INSTALL-DIR>/svn-replicator/utils/) which contains three conversions scripts. You will need to apply the script that corresponds with the version of SVN MultiSite from which you are upgrading. i.e.

Converts all builds of SVN MultiSite 4.2 into the latest data format

Set your imported users as "local"

perl convertac42-42-latest.pl backup.xml local

Set your imported users as "LDAP"

perl convertac42-42-latest.pl backup.xml ldap 

Running the conversion script will create a new file in the utils folder.

Converted from SVN MultiSite 4.2
Use this file for the following steps. Please note that running the script from any other folder will not work.

7. Import your saved settings

So you backed up your data, installed the latest version MultiSite, if it was neccessary, undated your backup for import into the latest version of MultiSite. Now it's time to import your backed up data.

Use this procedure to restore user information, although any system settings will need to be manually applied. Important: if you're using LDAP then you should re-enter your LDAP authoritie before importing your users.

7.1 From the Admin Console, click on the System tab. Click on Import Settings. Click on the magnifying glass browse icon and navigate to the utils folder.
upgrade with backup

7.2. Select the new MS425-convert-access-control.xml file, then click on the Import Settings button.
upgrade with backup

7.3 You'll see the import bar progress until you get an "import complete" message. upgrade with backup

7.4 When the import is complete check that the users, teams and rules have been imported successfully from the previous MS installation. Test the individual node by trying an svn checkout with the the imported configuration. Also, manually add the svn repositories you are using under Proxy/SVN Settings.

Important All files for use with WANdisco MultiSite should use UTF-8 encoding (and/or single-byte encoding if there are no none-ASCII characters). Any other encoding e.g. Unicode will not be parsed correctly.

7.5. You've now completed the upgrade. Check that your settings such as scheduled DN rotation and consistency checks are still setup to your requirements. Complete some test commits and check the dashboard to ensure that replication is working.

Using the Upgrader script

You can read more about how to use the upgrader script by running it with the -help flag.

$ java -jar svn-replicator.jar -help

** Alert! ** Alert
Valid parameters are:

-dprefs show dynamic preferences.
-nodes show node information.
-upgrade <path> upgrade an existing installation at the specified path.
-upgradeNoConfirm <path> upgrade an existing installation at the specified path WITHOUT PROMPTING FOR CONFIRMATION.
-help | -h show help