Upgrade Guide

Although you can update to the latest version of SVN MultiSite Plus by completing a fresh installation (following the Installation Guide), you would need to recreate your configuration for node, repository and replication group settings. This upgrade procedure describes how to upgrade and keep most of your existing configuration.

Which version are you running?
The version number of each SVN MultiSite Plus component is tracked. You need to know the svn-ms-replicator version. You can see this:

Listed at the bottom of the admin UI
Listed at the bottom of the Settings tab of the admin UI, along with other component versions
In this file, accessible without starting up:
```
/opt/wandisco/svn-multisite-plus/VERSION
```

1. From SVN MultiSite Plus 1.2 Build: 6903 to later

1.1 Before you upgrade

Before starting an upgrade:

Recheck the deployment checklist.

All repositories must have unique names
Duplicate repository names are not allowed. In earlier versions you could give separate repositories the same name. This caused no problem for the replication engine but could confuse users and lead to serious user errors.

Important: Before upgrading you should check your existing repositories and ensure that there are no duplicate names. If necessary, rename existing duplicate repositories.

Back up existing Apache config files. When the upgrade is completed you should verify that it hasn't made Apache configuration changes that will adversely affect your operation.
Do not make any system changes, like adding new repositories, until the upgrade has been completed.

Notifications are lost after an upgrade
Note: These steps are only required if upgrading from 1.2. or earlier.
The email notification system is not incorporated into the upgrade process. Performing an upgrade removes any notifications set up on your system. To restore your notication settings either re-enter them after completing the upgrade or, before starting an upgrade, Backup and Restore Notification Settings.

IMPORTANT: upgrade one node first, then upgrade the rest in parallel
Select one node and run the upgrade on this node to completion. Type y to the question:

Is this the first node? y/N:

When this is complete you can then upgrade all the other nodes in parallel by typing n to answer this question.
Do not bring up any node until ALL of the nodes have been upgraded.

IMPORTANT: SSL Upgrades
SSL upgrades from build 5435 fail with the error:

Unable to determine application version numbers, curl returned 60", Issue NV-2273.

There is a simple workaround:

Open the backup script at svn-multisite-plus/bin/backup
Modify line 27 by adding -k after -f, i.e. change script from
```
alias curl='curl -f -u $USERNAME:$PASSWORD'
```
to
```
alias curl='curl -f -k -u $USERNAME:$PASSWORD'
```
This works around the problem. The problem will be fixed in the next release.

Installing with ACP 1.5 auditing functionality
If you are also installing Access Control Plus 1.5 with auditing functionality, make sure that you set the following variables:

FLUME_INSTALL_DIR: Flume install location for /opt/wandisco/flume_sender
Do not set the Flume install var to a directory that is unaccessible, i.e. one that is not writable by anyone, including root.
ENABLE_AUDITING: Set to true to install auditing and false to not install auditing.
For detailed information see ACP installation instructions.

Also refer to Manual set up instructions for audit logging.

Changes to Tiebreaker node availability
In SVN MultiSite 1.6 the functionality for tiebreaker nodes change slightly. After upgrading from an earlier version of SVN MultiSite Plus, if you make a change to a replication group that has an odd number of voter nodes, including a change to the schedule, any tiebreaker nodes will now lose their special tiebreaker designation. Tiebreaker nodes are now only available when there is an even number of nodes - along with the corresponding risk that a vote could be evenly split between voters. Note that this change is not applied after upgrading to SVN MultiSite 1.6 but only after you then alter an applicable replication group.

1.2 Upgrade procedure

If your upgrade of the initial node fails for any reason, then you must contact WANdisco Support immediately, without trying to upgrade any other nodes.

IMPORTANT: Shutdown Apache
When upgrading to version 1.6 from any previous version, shutdown Apache on all nodes before starting. This is because changes in the 1.6 release could invalidate data cached by Apache. Don't forget to restart Apache once all nodes have been upgraded.

Open a terminal window and log in to the server.
Get the latest installer file and make sure it is executable:
```
chmod a+x svn-multisite-plus.sh
```

Run the installer:

./svn-multisite-plus.sh
Verifying archive integrity... All good.
Uncompressing WANdisco SVN MultiSite Plus........................
Running in non-interactive mode, installing with user 'wandisco' and group 'wandisco'. Output will be logged
to the daemon.info syslog facility

Please enter the username of an administrative user: admin
Please enter password for the 'admin' administrative user:xxxxxxxxxx

This process must be run on ALL nodes individually, in sequence. NOT AT THE SAME TIME
If this is the first node we will use this node to co-ordinate the upgrade.
Is this the first node? y/N: y

Stopping ui:..[  OK  ]
Stopping replicator:..[  OK  ]

Backup process logged at /opt/wandisco/svn-multisite-plus/logs/backup.log

Version 1.2.2-SNAPSHOT Build: 29412 backup found in /opt/wandisco/svn-multisite-plus/replicator/database
/backup/2014-06-17T16:58:54Z_DConE_Backup

......................................

Transformation complete
Jun 17, 2014 4:59:22 PM com.wandisco.fsfs.backup.FsfsRestore main
INFO: main:[About to restore database from /opt/wandisco/svn-multisite-plus/replicator/database/
backup/2014-06-17T16:58:54Z_DConE_Backup to /opt/wandisco/svn-multisite-plus/replicator/database]



Checking SVN
SVN version 1.7.9-2 is already installed, will not install SVN


Beginning WANdisco SVN MultiSite Plus Installation...
Attempting to run backup on existing install of SVN MultiSite Plus...

Ignore the installation script warning that you should upgrade the nodes "individually, in sequence"!

As SVN MultiSite Plus is already installed and running, the installer determines that you wish to perform an upgrade instead of an initial installation:

SVN MultiSite Plus Pre-Upgrade Backup Script

Please enter password for the 'admin' administrative user:

Enter the SVN MultiSite Plus admin credentials:

Initiating synchronised stop...
Node has achieved synchronised stop
Initiating database dump...
Database dump complete
Stopping ui:.                                              [  OK  ]
Stopping replicator:.                                      [  OK  ]
Performing backup...
Backup has been stored in /opt/wandisco/svn-multisite-plus/var/backups

Starting ui:[  OK  ]
Starting replicator:[  OK  ]

Backup process logged at /opt/wandisco/svn-multisite-plus/logs/backup.log

Version 1.2.2-SNAPSHOT Build: 29412 backup found in
/opt/wandisco/svn-multisite-plus/replicator/database/backup/2014-06-17T16:58:54Z_DConE_Backup
......................................

Transformation complete
Jun 17, 2014 4:59:22 PM com.wandisco.fsfs.backup.FsfsRestore main
INFO: main:[About to restore database from /opt/wandisco/svn-multisite-plus/replicator/
database/backup/2014-06-17T16:58:54Z_DConE_Backup to /opt/wandisco/svn-multisite-plus/replicator/database]
Jun 17, 2014 4:59:22 PM com.wandisco.database.prevayler.DatabaseInstance createLocation
INFO: main:[Writing to database location /opt/wandisco/svn-multisite-plus/replicator/database]
Jun 17, 2014 4:59:22 PM com.wandisco.database.prevayler.Manager create

The installer stops your nodes, then backs up the application data. The repository data is not touched.

If the synchronized stop failed in the previous step:

Ensure that no corresponding repositories are stuck in Local Read-only mode.
Ensure that there's at least one defined replication group on the nodes, which is required for a synchronized stop.
Reset all nodes to clean out any pending proposals then retry the upgrade.

With the local replicator restarted, log in to the admin UI and click the Settings tab. You can confirm that SVN MultiSite Plus has been updated by looking at the Module versions.

IMPORTANT: Do not bring up any node until ALL of the nodes have been upgraded.
When each node has been updated, one at a time, navigate to the Nodes tab on the admin UI and wake up the nodes. You can do this on each individual node in turn or you can use the Start All button - 14. Starting nodes.

Which version am I running?
The version number of each SVN MultiSite Plus component is tracked. You need to know the svn-ms-replicator version which is:

Listed at the bottom of the admin UI
Listed at the bottom of the Settings tab of the admin UI, along with other component versions
In the following file, accessible without starting up:
```
/opt/wandisco/svn-multisite-plus/VERSION
```

2. Migration from SVN MultiSite 4.2

This section gives important information if you're upgrading from an earlier version of SVN MultiSite.

2.1 Replica consistency

Summary: SVN MultiSite Plus uses a stronger definition of "identical"

SVN MultiSite 4.x and earlier versions require that repository replicas are "identical", in that all replica contain identical revisions. SVN MultiSite Plus uses a stronger definition of "identical" in that the repositories must now be byte-for-byte the same (identical in terms of properties, time-stamps, etc).

A migration from SVN MultiSite to SVN MultiSite Plus therefore requires that you ditch all but one copy of each repository. This remaining copy becomes your "master" and must be copied to each applicable node. This ensures that you start from the position where replica are identical.

2.2 Migration strategy

Per-repository:

Repostories are migrated one at a time.
There is less risk.
This is the preferred approach if installing on existing servers.
May not be able to preserve the repository URL.

Full migration:

All repositories are migrated in a single operation.
"all your eggs in one basket" risk.
The preferred approach when installing onto new servers.
Biggest obstical is managing the migration of repository data.

2.3 Copying strategy

In production, repositories can be extremely large, so large that making copies of them can be challenging. There are a number of strategies you can use to manage the distribution of

Strategy 1: Make a physical copy of each repository for real-world trasit. This option makes most sense when the scale of repository data is so great that a WAN network transfer is not practical (e.g. copying Terrabytes of repository data over a low/moderate bandwith connection).

Strategy 2: Full rsync (without checksum). This option is a direct solution that works best if you have the opportunity to copy all repository data during a maintenance window. You won't be able to continue commiting changes to the original repositories once done.

Strategy 3: Incremental rsync (with checksuming). This option takes a copy of the repository from each location's local server, and then uses an incremental rsync with checksums to make the new copy identical to the master copy. The best way to accomplish this is to mount the storage of the MultiSite 4.2 node in read-only mode on the MultiSite Plus service, then copy the data to the real location on the MultiSiet Plus node.

2.4 Periodic incremental synchronization

This approach updates MultiSite Plus copies of the repository with the commits made since the last rysnc. Note that the following steps will update the MultiSite Plus copies of the repositories with the commits made since the last rsync. However, these repositories are not guaranteed to be correct. The next section explains how to finalise the repository synchronization before it can be replicated by MSP.

2.5. Finalize the copy

To guarantee a correct repository, you need to run a final incremental rsync after the repository has been made read-only.

3. Roll back to an earlier version

Important requirement for rolling back from 1.6
There is a bug in the rollback script that will untar your backed-up application data to the application's root path but will add the root path, e.g /opt/wandisco/svn-multisite-plus/opt/wandisco/svn-multisite/plus/.

If you perform a rollback, there's a temporary workaround required to correct the above issue. You must identify whether your backup tar file is APPLICATION_ROOT relative or ROOT relative and, if ROOT relative then you will need to add the "-C /" Option (for setting the target directory) to the "tar -xzf" command. E.g.

tar -xzf -C / <backup-file>

Follow these steps to roll back SVN MultiSite Plus to an earlier version:

Stop the service:
```
service svn-multisite-plus stop
```

Backup your existing installation:

cp -rp /opt/wandisco/svn-multisite-plus /opt/wandisco/svn-multisite-plus-bak

Uninstall MSP:
```
yum -y erase svn-multisite-plus
```
Remove product files:
```
rm -rf /opt/wandisco/svn-multisite-plus
```
Fully complete the installer for the prior version.
Note: The existing product license will be at /opt/wandisco/svn-multisite-plus-bak/replicator/properties/license.key

Copy the MSP backup that was generated during upgrade:

mkdir /opt/wandisco/svn-multisite-plus/var/backups
cp -rp /opt/wandisco/svn-multisite-plus-bak/var/backups/* /opt/wandisco/svn-multisite-plus/var/backups/

Run the rollback script:

cd /opt/wandisco/svn-multisite-plus/bin
./rollback

This stops the service.

Start the service:
```
service svn-multisite-plus start
```
Check that the version number on the Settings page is correct. Note: You may have to clear your browser's cache.
Check also that core functionality is correct, i.e. CO, CI, replication, etc.

In the earlier version you will see that recent features are no longer present. All inducted nodes, replication groups, and repositories, etc. are still present and correct.