6. Upgrade to the latest version
Upgrading to Access Control Plus 1.5 enabling wildcards
ACP 1.5 allows you to use wildcards to report on directory entries such as files, directories and symbolic links. See Enable wildcard support.
This section describes what you need to consider to upgrade an existing copy of WANdisco's Access Control / Access Control Plus. We cannot address every set of conditions so take care to consider all possible problems. If you have any questions or concerns, contact WANdisco support team.
Check component compatibility
When upgrading Access Control Plus, Git MultiSite or Subversion MultiSite Plus, you must upgrade the Generic File Replication script to match your version of these products. We have tested ACP 1.0 (build 1266) and ACP 220.127.116.11 (build 6503) with ACP GFR 1.0 (build 1635) and MSP/GitMS 1.1 and earlier. ACP 1.0.1 (build 1737) was tested with ACP GFR (build 1737) and MSP/GitMS 1.2* and 1.3.0, 1.3.1. Contact WANdisco Support to plan an upgrade to a later version.
ACP 1.5.3 (Build 2336) was tested with ACP GFR (build 2336) and MSP/GitMS 1.5.3.
Upgrading to Access Control Plus 1.5 with auditing
You will need to set several environment variables when you upgrade to ACP 1.5 and enable the auditing functions. See Install auditing function.
Upgrading from Access Control Plus 1.0 to 1.5 requires upgrade to 1.1 first
To upgrade from Access Control Plus 1.0 to 1.5, you must first upgrade to 1.1. Then, from 1.1, upgrade to 1.5 by repeating the steps described in this section. If you have problems, follow the rollback procedure and contact WANdisco support team.
Upgrading from Access Control 4.2
To upgrade from Access Control 4.2 to Access Control Plus you must contact WANdisco support team. This is necessary to complete the validation using new scripts.
6.1 Upgrade overview
This section gives an 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.
The Pre-installation step invokes the backup script which stores the system and user settings that are imported into the latest version.
Installing Flume while upgrading
If you are running a version of Access Control Plus that didn't include Flume, It's possible to install Flume during an upgrade of Access Control Plus. See 6.7 Install Auditing. The procedure differs a little from that used when installing both ACP and Flume from scratch. For that, see 3.1 Install Auditing Function.
6.2 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.
WARNING: Disable batch updates before shutting down for upgrade
You must complete these steps before shutting down. We recommend that you disable batch updates at least 1 hour before you shut down the application.
- Log in to Access Control Plus.
- Click Settings.
- Click Access Control Updates.
- Click the Disable Batch Updates button.
WARNING: After an upgrade you must re-enable batch mode (an upgrade installation disables batch mode so that the upgrade progresses).
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
6.3 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:
- Open a terminal window and log in to the server.
- Get the latest installer file and make sure it is executable:
chmod a+x scm-access-control-plus_rpm_installer.sh
- Run the installer:
After providing Access Control Plus admin credentials, the installer script verifies that there's an existing installation and completes 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
- The installer performs the upgrade. 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 ]
Note: Do not run replace-link yet - repeat the upgrade on all nodes
At the end of the upgrade you see a message about running replace-link. Do not run this yet. First you need to repeat the upgrade on all your nodes.
6.4 Post upgrade: bring nodes back up
When all nodes have been upgraded, bringing them back up by running:
6.5 Enable wildcard support
Upgrading Access Control Plus to v1.5 includes wildcard support:
- Every rule-specific resource can be enabled to have a priority, and this influences the placement of the section within the AuthZ file. A setting can be stored for the collapsed section priority choice (the lower the number the higher position in the file).
- Highest priority is the default. We recommend that you do not change this. Contact Wandisco Support for advice on this.
- Wildcards are either enabled globally or not enabled at all.
- If wildcard support is enabled, there is no way to disable it. This is true even if there are no wildcard rules set.
For more detailed information about wildcards, see Admin Guide.
With Subversion, MultiSite Plus and Access Control Plus installed:
- Click Settings then Connect to MultiSite.
- Click the check box Enable Wildcards. Note:
This cannot be undone without reinstalling
- Select either:
- High Priority
- Low Priority
Default is High Priority. See Setting priorities
- Click Save.
The wildcards option is now enabled for rules applying to MultiSite Plus repositories.
Note that you can change the priority setting at any time.
Remember: You cannot disable wildcard support when wildcard rules have been set.
6.6 Roll back
If you need to roll back from an attempted upgrade and return to your current installation, for example going back from 1.5 to 1.1.1:
- From the
/opt/wandisco/scm-access-control-plus/backupsdirectory, copy the file similar to
scm-access-control-plus-backup_20141217154840.tar.gzto somewhere safe.
- 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 back up the install directory, eg
- Re-install the previous version of Access Control Plus.
- Stop the replicator.
- Ensure that the permissions are correct.
- Run the rollback script.
cd /opt/wandisco/scm-access-control-plus/bin ./rollback
- Repeat the rollback procedure on each node.
- When all nodes have been rolled back, start ACP via the scm-access-control-plus service start as usual.
Your nodes will start up, returning production to the earlier version of Access Control Plus.
6.6 Import 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.
- On your Access Control/SVN MultiSite 4.2 deployment, perform a sync stop.
- 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.
- You may need to perform a cleanup of the export. Contact WANdisco's support team about whether this will be necessary.
- 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.
- 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.
6.6.2 Install Access Control Plus
- Run through the instructions provided in the Deployment Guide.
- When 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
- Providing that you have logged on with appropriate permissions, you can run the script as follows:
- 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
- You can confirm the import was successful by viewing the available accounts in Access Control Plus.
- 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 your rules will 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.
- 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. This means that, in a rules conflict, the most favorable rule is applied.
- 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.
6.7 Install Auditing (through Apache Flume)
These steps are only for a first-time installation of Flume, during an upgrade of Access Control Plus.
Multi-stepped ACP upgrade
If you are upgrading from an old version of ACP and therefore need to complete a sequence of consecutive ACP upgrades, leave the installation of Flume until the final upgrade step. A case in point: ACP 18.104.22.168 requires an older version of Flume (22.214.171.124) If you install Flume at this stage, you'll end up needing to complete an upgrade of Flume as well.
It makes sense to handle the Flume installation during the upgrade to 1.7.2.
There are two ways to install flume
- interactive (manual)
- and non-interactive (silent)
Use ACP's installer to handle the upgrade, the installer will detect that you are performing an upgrade and that Flume is not yet installed. The installer will ask:
Just answer the brief series of question to install Flume.
Do you wish to install auditing components for use with Access Control Plus? (Y/n)
For the non-interactive upgrade, to install Flume for a first time for ACP you will need to set the following variables:
ENABLE_AUDITING=true FLUME_INSTALL_DIR:Flume install location for acp-flume-receiver ACP_USER_ID: Logger user ID to connect flume->acp ACP_USER_PASSWORD: Logger user password to connect flume->acp ACP_USER_EMAIL: Logger user email ACP_AVRO_HOST: Flume receiver IP ACP_AVRO_PORT: Flume receiver port FLUME_ACP_HOST: ACP IP for Flume to connect to FLUME_ACP_PORT: ACP rest port for Flume to connect to FLUME_AVRO_SSL: true/false to enable/disable SSL FLUME_AVRO_KEYSTORE_LOC: Only required if FLUME_AVRO_SSL=true, keystone location FLUME_AVRO_KEYSTORE_PASS: Only required if FLUME_AVRO_SSL=true, keystone password FLUME_AVRO_TRUSTSTORE_LOC: Only required if FLUME_AVRO_SSL=true, truststore location FLUME_AVRO_TRUSTSTORE_PASS: Only required if FLUME_AVRO_SSL=true , truststore password INSTALL_FLUME_ON_UPGRADE=set to true if first install of flume on an upgrade
An example of these exports would be like the following (excluding the use of SSL)
export ENABLE_AUDITING=true export FLUME_INSTALL_DIR=/opt/wandisco/flume-scm-access-control-plus export ACP_USER_ID=logger export ACP_USER_PASSWORD=logger export ACP_USER_EMAILemail@example.com export ACP_AVRO_HOST=localhost export ACP_AVRO_PORT=8441 export FLUME_ACP_HOST=localhost export FLUME_ACP_PORT=8441 export FLUME_AVRO_SSL=false export INSTALL_FLUME_ON_UPGRADE=true
Once you have exported these variables, run the upgrade.
Copyright © 2005-2016 WANdisco, Inc.
All rights reserved
This product is protected by copyright and distributed under licenses restricting copying, distribution and decompilation.
Access Control Plus v126.96.36.199
Last doc issue: 17 June 2016