2.6 Upgrade to the latest version

In this section we cover everything that you need to consider before upgrading an existing copy of WANdisco's Access Control / Access Control Plus. It isn't possible to address every possible set of conditions so it's important to remain watchful for possible problems - don't hesitate to contact our support team with any questions or concerns.

Upgrading from Access Control 4.2
If you're upgrading from the previous version of Access Control, rather than an earlier version of Access Control Plus, you'll need to follow the instructions for a fresh installation, after completing a backup of your 4.2 settings. See Importing Access Control 4.2 backup data

Upgrade Overview

What follows is a broad overview of the upgrade procedure. The procedure starts with creating a import file by invoking the export script in the current installation. This stores system and user settings in an external XML file for later re-importation. Next, the upgrade script is run. This takes the latest JAR files and places them into the current install. The final post-install portion performs any necessary changes to database structure and restores the previous installation's settings.

During the Pre-installation step we invoke the backup script which stores the system and user settings that we'll import into the latest version.

Pre-upgrade

Turn off Batch Updates

Perform the upgrade during a time when you can halt SCM activity. If you are running with Batch Mode on, this needs to be disabled and Access Control Plus will need enough time to catch up with all batched operations.

  1. Log in to Access Control Plus.
  2. Click on Settings.
  3. Click on Access Control Updates.
  4. Click on the button Disable Batch Updates.

Known Issue - Existing/earier backups
During the upgrade, the Access Control Plus settings and internal database will be backed up and placed in the directory /opt/wandisco/scm-access-control-plus/database/backup/. Before you start the upgrade we recommend that you move any pre-existing archive files out to a different location. Currently the upgrade script can fail if it detects other multiple archive files. We'll fix this issue in a future release.

IMPORTANT
If you perform an import from an earlier version of Access Control you must ensure that Access Control Plus does not poll the LDAP authorities during the process. You can do this by setting the Synchronisation Period to 999 (minutes) - Just for the duration of the import

Upgrade Procedure

Having completed the necessary pre-upgrade steps, it's now time to complete the upgrade. You'll need to have downloaded the installer for the latest version of Access Control Plus. Place the script on your server and run through the following steps:

  1. Open a terminal window and login to the server.

  2. Get the latest installer file and make sure it is executable:
    chmod a+x svn-multisite-plus.sh
    	  
  3. Run the installer: After providing Access Control Plus admin credentials, the installer script will verify that there's an existing installation and complete the necessary back up of settings.
          [root@redhat6 wandisco]# ./scm-access-control-plus_rpm_installer.sh
          Verifying archive integrity... All good.
          Uncompressing WANdisco Access Control 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 the password for 'admin':
          Checking credentials: OK
          State machines are stopped
          Backing up platform: OK
          Backing up ACP: OK
          Backup complete
          
    Next, the installer performs the upgrade itself. In most cases the installer handles everything.
          Stopping scm-access-control-plus:.[  OK  ]
          Upgrading from version 1.0.1
          Starting upgrade of backup found in /opt/wandisco/scm-access-control-plus/database/backup/2014-07-28T13:30:19Z_DConE_Backup
          ..............................
          Transformation complete
          Jun 27, 2014 4:26:43 PM com.wandisco.acp.backup.Restore main
          . . . . . . . . 
          Please run '/opt/wandisco/scm-access-control-plus/bin/replace-link' once all nodes have been upgraded. This will automatically start the replicator.
          Stopping scm-access-control-plus services...
          Stopping scm-access-control-plus:[  OK  ]
          
          
          
    You will note that at the end of the upgrade you will see a message about running replace-link. Don't run this yet. First you need to complete the upgrade on all your nodes.

Repeat for all nodes

Repeat the upgrade procedure for all other nodes before moving on to the next section.

Once all nodes have been upgraded, bringing the nodes back up is done by running an extra script:

./opt/wandisco/scm-access-control-plus/bin/replace-link

Rollback

In the event that you need to roll back from an attempted upgrade, returning to your current installation.

  1. Copy the back up for safe keeping.
  2. Uninstall the current version of ACP.
    	
    	[root@redhat6 init.d]# yum remove scm-access-control-plus
    	Loaded plugins: product-id, rhnplugin, security, subscription-manager
    	Updating certificate-based repositories.
    	Setting up Remove Process
    	Resolving Dependencies
    	--> Running transaction check
    	---> Package scm-access-control-plus.noarch 0:1.0.1-1711 will be erased
    	--> Finished Dependency Resolution
    	epel/metalink                                            |  27 kB     00:00
    	epel                                                     | 4.4 kB     00:00
    	epel/primary_db                                          | 6.3 MB     00:00
    	
    	Dependencies Resolved
    	
    	================================================================================
    	 Package    Arch   Version    Repository                                   Size
    	================================================================================
    	Removing:
    	 scm-access-control-plus
    		    noarch 1.0.1-1711 @/scm-access-control-plus-1.0.1-1711.noarch  55 M
    	
    	Transaction Summary
    	================================================================================
    	Remove        1 Package(s)
    	
    	Installed size: 55 M
    	Is this ok [y/N]: y
    	Downloading Packages:
    	Running rpm_check_debug
    	Running Transaction Test
    	Transaction Test Succeeded
    	Running Transaction
    	  Erasing    : scm-access-control-plus-1.0.1-1711.noarch                    1/1
    	Stopping scm-access-control-plus services...
    	Stopping scm-access-control-plus:[  OK  ]
    	Installed products updated.
    	  Verifying  : scm-access-control-plus-1.0.1-1711.noarch                    1/1
    	
    	Removed:
    	  scm-access-control-plus.noarch 0:1.0.1-1711
    	
    	Complete!
    	
    You can then delete or backup the install directory, eg /opt/wandiso/ scm-access-control-plus
  3. Re-install the previous version of Access Control Plus.
  4. Stop the replicator.
  5. Run the rollback script.
    cd /opt/wandisco/scm-access-control-plus/bin
    		./rollback
    	
  6. Repeat the rollback procedure on each node.
  7. Once all nodes have been rolled back it is crucial that they are started in a synchronized manner. For this you will need to manually call the nodes via the Rest API, as follows:
    curl -X PUT http://<Server_IP>:<Server_UI_PORT>/dcone/statemachines/coordinatedstartall --user <USERNAME>:<PASSWORD>

Your nodes will start up, returning production to the earlier version of Access Control Plus.

Importing Access Control 4.2 backup data

An upgrade from Access Control/Subversion MultiSite 4.2 assumes that you are running with the latest 4.2 versions.

Pre-install

  1. On your Access Control/SVN MultiSite 4.2 deployment, perform a sync stop.
  2. Run the Export tool, creating a backup directory.

    Important: Local Admin Account
    When you import this exported 4.2 data, the existing Access Control Plus data will be removed, including the local admin account. You should ensure that there is a local admin account present on your 4.2 deployment prior to completing this export. Furthermore, ensure that you don't disable local accounts on Access Control Plus prior to re-importing the data.

    Should you get locked out of Access Control Plus you can run the Password change/recovery utility which will enable local account access and prompt you to create a new admin account
    - 3.4 Password change/recovery.

  3. You may need to perform a cleanup of the export. Consult with WANdisco's support team about whether this will be necessary.
  4. Shutdown Access Control/SVN MultiSite 4.2. You may wish to save the installation to an archive so that it's no longer present on the server.
  5. If you're installing SVN MultiSite Plus then delete your current installation of Subversion. The latest version of MultiSite requires that you install a modified version of SVN.

Install Access Control Plus

  1. Run through the instructions provided in the Deployment Guide.
  2. Once the installation and node induction is complete you can run the special import script that is available in the Access Control Plus installation which handles 4.2 backup files. Login to the server via a terminal and navigate to the bin directory, by default this is /opt/wandisco/scm-access-control-plus/bin/.
  3. Providing that you have logged on with appropriate permissions, you can run the script as follows:
    ./import42backup
  4. You will need to provide Access Control Plus admin login credentials. You'll then be asked for a the absolute path to the 4.2 backup. e.g.:
    "Path to the backup directory to use: 2014-05-30.12-139-25_cfdc4-3r3ro-3r3-3rr3nfvfeef" etc
  5. You can confirm the import was successful by viewing the available accounts in Access Control Plus.
  6. Important:
    Access Control Plus does not provide the "Strict" alternate (Restrictive) mode for interpreting Authz rules which was available in Access Control 4.2. If you were applying "Restrictive Mode" in your 4.2 deployment then you can expect your rules to be applied differently in Access Control Plus. Read more about Restrictive Access Control Mode in 4.2

    You must complete a full review and or rewrite of your rules if you need Access Control Plus to exactly recreate the way that your 4.2 deployment's Access Control worked.

    "Allow rules" overrule Denies

    Access Control Plus interprets Authz rules in the same way as mod_authz_svn, in this case Access Control Plus applies rules in reverse of the restrictive mode, i.e. READ-WRITE, READ-ONLY then DENY. So that in a rules conflict, the most favorable rule is applied.

    Important:
    The handling of case sensitivity has changed between version 4.2 products and Access Control Plus/ SVN MultiSite Plus
    The Apache/svnserve/git configuration used to serve repositories to end-users must correctly reflect the Case settings. This includes downcasing the usernames (See Downcasing) before passing them to AuthZ and not mixing the case sensitive and insensitive users in the same AuthN blocks. Each set of users would require separate location blocks in Apache, one of them using AuthzForceUsernameCase or similar.