How to Migrate from r12.1 SP3

Web Services Security Guides › CA SiteMinder® Web Services Security Upgrade Guide › Upgrading from CA SOA Security Manager r12.1 SP3 › How to Migrate from r12.1 SP3

How to Migrate from r12.1 SP3

Complete the following procedures to migrate from r12.x to 12.52:

Review the installation and upgrade considerations in the Policy Server Release Notes.
(Optional) If your environment includes multiple instances of smkeydatabase, synchronize all instances. Part of the Policy Server upgrade includes migrating all content in the smkeydatabase to the certificate data store.
Review the sections in Before You Upgrade the Policy Server.
Upgrade an r12.1 SP3 Policy Server to 12.52.
Upgrade an r12.1 SP3 SOA Agent to 12.52.
Upgrade the remaining r12.1 SP3 Policy Servers and SOA Agents to 12.52, respectively.
Upgrade the r12.1 SP3 policy and key stores to 12.52.
Upgrade the r12.1 SP3 Administrative UI.

More information:

Installation and Upgrade Considerations

More information:

CA SiteMinder® Key Tool

Synchronize Key Database Instances

Synchronize all smkeydatabase instances before beginning the migration to a new version.

Note: Use the smkeytool utility to synchronize the smkeydatabases and resolve all data inconsistencies between smkeydatabase instances. For more information about the smkeytool utility, see the Policy Server Administration Guide.

Previous versions of CA SiteMinder® used a local smkeydatabase to store certificate data. Each Policy Server required its own smkeydatabase. For version 12.52, a centralized certificate data store replaces the local smkeydatabases.

As part of a Policy Server upgrade, the installer automatically backs up the local smkeydatabase and tries to migrate all content to the certificate data store. This process includes a comparison of both stores before starting the migration.

Important! If the migration of the smkeydatabase fails, do not return the Policy Server to the environment. Returning the Policy Server after a failed migration causes all transactions that require the certificate data to fail.

Use the following guidelines to identify and resolve data consistencies among your smkeydatabases:

Verify that each certificate‑authority certificate references certificate revocation lists consistently across instances.
Example: A certificate‑authority certificate consistently references certificate revocation lists in an LDAP directory service.
Verify that the defaultentpriseprivatekey alias represents the same private key/certificate pair in all instances.
Verify that the same alias maps to the same certificate or key/certificate pair.
Verify that the same certificate‑authority certificates map to the same certificate revocation lists.
Verify that a revoked or expired certificate is not present.
Verify that all CRL information is valid.

Important! After you resolve all data inconsistencies, we recommended that you do not modify a smkeydatabase until all migrations are complete.

Upgrade an r12.1 SP3 Policy Server

The following sections detail how to upgrade an r12.1 SP3 Policy Server on Windows and UNIX.

Before You Upgrade

Before you upgrade a Policy Server, consider the following items:

(Optional) If the environment contains multiple smkeydatabase instances, be sure to synchronize all content. Synchronizing resolves data inconsistencies that can prevent the Policy Server installer from automatically migrating content to the certificate data store.
You upgrade the Policy Server using the installation media on the Technical Support site.
Note: For a list of installation media names, see the Policy Server Release Notes.
(Linux) Be sure that the required Linux libraries are installed to the Policy Server host system. For more information, see Required Linux Libraries.
Remove the Policy Server from the environment. Removing the Policy Server prevents CA SiteMinder® Agents from contacting the Policy Server during the upgrade.
Shut down all instances of the Policy Server Management Console.
(UNIX) The user account upgrading the Policy Server must have executable permissions on the directory that contains the installation media. If the user account does not have these permissions, run the following command:
```
chmod +x installation_media
```
installation_media

Specifies the Policy Server installation executable.
(UNIX) If you execute the Policy Server across different subnets, it can crash. Run the Policy Server installer directly on the host system.
(UNIX) Upgrade the Policy Server using an account with at least the same permissions as the user who installed the Policy Server. For example, if a root user installed the Policy Server, upgrade the Policy Sever using a root user.
The CA SiteMinder® documentation is not installed with the Policy Server. We recommend that you locate the documentation before you upgrade.

More information:

Locate the Installation Media

Installation Media Names

Required Linux Libraries

Certain library files are required for components operating on Linux operating environments. Failure to install the correct libraries can cause the following error:

java.lang.UnsatisfiedLinkError

If you are installing, configuring, or upgrading a Linux version of this component, the following libraries are required on the host system:

Red Hat 5.x:

compat–gcc-34-c++-3.4.6-patch_version.I386

libstdc++-4.x.x-x.el5.i686.rpm

Red Hat 6.x:

libstdc++-4.x.x-x.el6.i686.rpm

Additionally, for Red Hat 6.x (64-bit):

Note: All the RPM packages that are required for 64-bit Red Hat 6.x are 32-bit packages.

libXau-1.0.5-1.el6.i686.rpm

libxcb-1.5-1.el6.i686.rpm

compat-db42-4.2.52-15.el6.i686.rpm

compat-db43-4.3.29-15.el6.i686.rpm

libX11-1.3-2.el6.i686.rpm

libXrender-0.9.5-1.el6.i686.rpm

libexpat.so.1 (provided by expat-2.0.1-11.el6_2.i686.rpm)

libfreetype.so.6 (provided by freetype-2.3.11-6.el6_2.9.i686.rpm)

libfontconfig.so.1 (provided by fontconfig-2.8.0-3.el6.i686.rpm)

libICE-1.0.6-1.el6.i686.rpm

libuuid-2.17.2-12.7.el6.i686.rpm

libSM-1.1.0-7.1.el6.i686.rpm

libXext-1.1-3.el6.i686.rpm

compat-libstdc++-33-3.2.3-69.el6.i686.rpm

compat-db-4.6.21-15.el6.i686.rpm

libXi-1.3-3.el6.i686.rpm

libXtst-1.0.99.2-3.el6.i686.rpm

libXft-2.1.13-4.1.el6.i686.rpm

libXt-1.0.7-1.el6.i686.rpm

libXp-1.0.0-15.1.el6.i686.rpm

Korn Shell (ksh) Package Required on Linux

The ksh Korn shell is required during Policy Server installation and upgrade on Linux platforms. Verify that the appropriate version for your Linux environment is installed.

Red Hat 5.x 32-bit

ksh-20100621-12.el5.i386.rpm

Red Hat 5.x 64-bit: ksh-20100621-12.el5.x86_64.rpm
Red Hat 6.x 32-bit: ksh-20100621-16.el6.i686.rpm
Red Hat 6.x 64-bit: ksh-20100621-16.el6.x86_64.rpm

Upgrade a Policy Server on Windows

Follow these steps:

Review Before You Upgrade.
Exit all applications that are running.
Navigate to the installation media.
Double–click installation_media.

installation_media

Specifies the name of the Policy Server installation executable.

The Policy Server installer starts.

Note: For a list of installation media names, see the Policy Server Release Notes.
Considering the following items when running the installer:
- The installer prompts you to select the components. When selecting components:
  - Reconfigure components that had been previously configured for the environment. Be sure to select the respective components.
  - If you do not intend on configuring a new policy store, clear the Policy Store check box. You do not have to reconfigure existing policy store settings. The Policy Server retains the policy store settings after the upgrade. You manually upgrade an existing policy store.
- If the installer detects a smkeydatabase, it:
  - Backs up the smkeydatabase.
  - Attempts to migrate the content to the certificate data store.
  Important! If the migration of the smkeydatabase fails, do not return the Policy Server to the environment. Returning the Policy Server after a failed migration causes all transactions that require the certificate data to fail.
Review the installation settings and click Install.
The Policy Server is upgraded. The selected components are configured for use with the Policy Server.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

Upgrade a Policy Server Using a GUI on UNIX

Follow these steps:

Review Before You Upgrade.
Exit all applications that are running.
Execute the following script in a ksh shell from the CA SiteMinder® installation directory:
```
../ca_ps_env.ksh
```
Note: Be sure that there is a space between the periods.
Open a shell and navigate to the installation executable.
Enter the following command:
```
./installation_media
```
installation_media

Specifies the name of the Policy Server installer executable.

The Policy Server installer starts.

Note: For a list of installation media names, see the Policy Server Release Notes.
Considering the following items when running the installer:
- The installer prompts you to select the components. When selecting components:
  - Reconfigure components that had been previously configured for the environment. Be sure to select the respective components.
  - If you are not configuring a new policy store, clear the Policy Store check box. You do not have to reconfigure existing policy store settings. The upgraded Policy Server retains the policy store settings. You manually upgrade an existing policy store.
- If the installer detects a smkeydatabase, it:
  - Backs up the smkeydatabase.
  - Attempts to migrate the content to the certificate data store.
  Important! If the migration of the smkeydatabase fails, do not return the Policy Server to the environment. Returning the Policy Server after a failed migration causes all transactions that require the certificate data to fail.
Review the installation settings and click Install.
The Policy Server is upgraded. The selected components are configured for use with the Policy Server.
Click Done.
Execute the following script in a ksh shell from the CA SiteMinder® installation directory:
```
../ca_ps_env.ksh
```
Note: Be sure that there is a space between the periods.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

Upgrade a Policy Server on UNIX Using a Console

Follow these steps:

Review Before You Upgrade.
Exit all applications that are running.
Execute the following script in a ksh shell from the CA SiteMinder® installation directory:
```
../ca_ps_env.ksh
```
Note: Be sure that there is a space between the periods.
Open a shell and navigate to the installation executable.
Enter the following command:
```
./installation_media -i console
```
installation_media

Specifies the name of the Policy Server installer executable.

The Policy Server installer starts.

Note: For a list of installation media names, see the Policy Server Release Notes.
Considering the following items when running the installer:
The installer prompts you to select CA SiteMinder® components. Each component is prefixed with a number. Type numbers separated with a comma (,) to select one or more components. Enter only a comma to select none of the features.
- Consider the following items when selecting components:
  - Reconfigure components that had been previously configured for the environment. Be sure to select the respective components.
  - Only select Policy Store if you are configuring a new policy store. You do not have to reconfigure existing policy store settings. The upgraded Policy Server retains the policy store settings. You manually upgrade an existing policy store.
- If the installer detects a smkeydatabase, it:
  - Backs up the smkeydatabase.
  - Attempts to migrate the content to the certificate data store.
  Important! If the migration of the smkeydatabase fails, do not return the Policy Server to the environment. Returning the Policy Server after a failed migration causes all transactions that require the certificate data to fail.
Review the installation settings and press Enter.
The Policy Server is upgraded. The selected components are configured for use with the Policy Server.
Click Done.
Execute the following script in a ksh shell from the CA SiteMinder® installation directory:
```
../ca_ps_env.ksh
```
Note: Be sure that there is a space between the periods.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

Custom Server–Side Code Requirements

Your Policy Server operating system determines whether recompiling custom server–side code is required. Use the following table to identify the requirement:

Operating System	Required?
Microsoft Windows and UNIX	No. Recompiling the custom code is optional.
Red Hat Linux	Yes. Upgrade the SDK and recompile the custom code using GCC 3.4.

Operating System

Required?

Microsoft Windows and UNIX

No. Recompiling the custom code is optional.

Red Hat Linux

Yes.

Upgrade the SDK and recompile the custom code using GCC 3.4.

Troubleshoot a Policy Server Upgrade

If you experience problems during the upgrade:

You can locate the Policy Server installation log file in siteminder_home\siteminder\install_config_info.

siteminder_home

Specifies the Policy Server installation path.
You can locate the smkeydatabase migration log (smkeydatabaseMigration.log) in siteminder_home\log.
Note: A Policy Server upgrade and a smkeydatabase migration are separate processes. If the smkeydatabase migration fails, the Policy Server upgrade does not fail.

Upgrade an r12.1 SP3 SOA Agent

Upgrading the r12.1 SP3 SOA Agents in the environment to 12.52 WSS Agents is the second step in the migration process. You can upgrade the SOA Agents in your environment in any order.

Note: CA SiteMinder® Web Services Security r12.1 SP3 SOA Agents can communicate with a 12.52 Policy Server. Therefore, you can upgrade your Policy Server to 12.52 before upgrading SOA agents while continuing to protect resources.

How to Prepare for a SOA Agent Upgrade

Prepare for upgrading a SOA Agent using the following process:

(UNIX) Be sure that you upgrade the SOA Agent with the same account that was used to install it. If you use a different account, the upgrade can fail.
Verify that the Policy Server is configured
Identify the required administrator and Policy Server object names
Identify SOA Agent requirements
Back up customized files
Replace existing read-only files during the upgrade (if prompted).

Verify the Policy Server is Configured

Before you upgrade the SOA Agent:

Be sure that the Policy Server can connect to the SOA Agent host system.
Be sure that the Policy Server is running before registering trusted hosts. You start the Policy Server on the Status tab of the Policy Server Management Console.

Identify the Required Administrator and Policy Server Object Names

Before upgrading the SOA Agent, you need the following information from the Policy Server administrator.

Name of the CA SiteMinder® Administrator allowed to register hosts.
Name of the Host Configuration Object.
Name of the Agent Configuration Object.

Identify WSS Agent Requirements

For more information about patches and other WSS Agent requirements, see the respective WSS Agent Guide.

Replace Existing Read-only Files

When you upgrade a SOA Agent, you may see messages asking whether you want to replace read-only files. Select Yes to all.

Upgrade an r12.1 SP3 SOA Agent

Use the 12.52 WSS Agent installer to upgrade a web agent.

Note: For more information about upgrading a SOA agent, see the respective WSS Agent Guide.

How to Upgrade an r12.1 SP3 Policy Store

Complete the following procedures to upgrade an r12.1 SP3 policy store to 12.52:

Stop all Policy Servers that are communicating with the policy store.
Import the policy store data definitions.
Import the default policy store objects.
If you configured policy objects related to generating SAML assertions using the FSS Administrative UI, run the XPS sweeper utility to complete the migration of your legacy federation objects.
Start all Policy Servers that are communicating with the policy store.

Stop all Policy Severs

Stopping all of the Policy Servers that are communicating with the policy store helps to prevent policy store corruption during the upgrade.

Follow these steps:

Log in to the Policy Server host system.
Complete one of the following steps:
- (Windows)
  1. Open the Policy Server Management Console and click Stop.
  2. Click OK to close the console.
- (UNIX) Use the following supplied script:
```
install_path/siteminder/stop-all
```
  install_path
  
  Specifies the Policy Server installation path.
Repeat this procedure for each Policy Server that is communicating with the policy store.

Import the Policy Store Data Definitions

Importing the policy store data definitions defines the types of objects that can be created and stored in the policy store.

Follow these steps:

Open a command window and navigate to siteminder_home\xps\dd.

siteminder_home

Specifies the Policy Server installation path.
Run the following command:
```
XPSDDInstall SmMaster.xdd
```
XPSDDInstall

Imports the required data definitions.

Import the Default Policy Store Objects

Importing the default policy store objects configures the policy store for use with the Administrative UI and the Policy Server.

Consider the following items:

Be sure that you have write access to siteminer_home\bin. The import utility requires this permission to import the policy store objects.

siteminder_home

Specifies the Policy Server installation path.
Before running a CA SiteMinder® utility or executable on Windows Server 2008, open the command line window with administrator permissions. Open the command line window this way, even if your account has administrator privileges. For more information, see the release notes for your CA SiteMinder® component.

Follow these steps:

Open a command window and navigate to siteminder_home\db.
Import one of the following files:
- To import smpolicy.xml, run the following command:
```
XPSImport smpolicy.xml -npass
```
- To import smpolicy–secure.xml, run the following command:
```
XPSImport smpolicy-secure.xml -npass
```
Note: You use either file to configure a new policy store and upgrade an existing store. When imported as part of an upgrade, the file does not overwrite existing default objects that were modified. Both files include the default policy store objects. These objects include the default security settings in the default Agent Configuration Object (ACO) templates. The secure file provides more restrictive security settings.

–npass

Specifies that no passphrase is required. The default policy store objects do not contain encrypted data.

The default policy store objects are imported.

Run the XPS Sweeper Utility

If you configured policy objects related to generating SAML assertions using the FSS Administrative UI, run the XPS sweeper utility (XPSSweeper) to complete the migration of these objects.

Follow these steps:

Log in to the Policy Server host system.
Run the following command to make available your legacy federation objects to the Administrative UI:
```
XPSSweeper
```
All legacy federation created using the FSS Administrative UI are available in the Administrative UI.

Start all Policy Servers

Starting all Policy Servers resumes communication between all of the Policy Servers and the upgraded policy store.

Follow these steps:

Log in to the Policy Server host system.
Complete one of the following steps:
- (Windows)
  1. Open the Policy Server Management Console and click Start.
  2. Click OK to close the console.
- (UNIX) Use the following supplied script:
```
install_path/siteminder/start-all
```
  install_path
  
  Specifies the Policy Server installation path.
Repeat this procedure for each Policy Server that is communicating with the policy store.

The policy store is upgraded.

How to Upgrade an r12.1 SP3 Administrative UI

Complete the following procedures to upgrade an r12.1 SP3 Administrative UI to 12.52 on Windows and UNIX.

Before You Upgrade

Consider the following items before you upgrade the Administrative UI:

Important! Review the Administrative UI upgrade options.
Upgrade the Administrative UI using the installation media on the Technical Support site.
Note: For a list of installation media names, see the Policy Server Release Notes.
Extract the executable for the prerequisite installer into the same directory that you extracted the Administrative UI installer. The installers must be in the same location so that the layout.properties file, included with the installation zip, is co-located with both executables.
The installation zip contains a layout.properties file at the same level as the installation media. If you moved the installation media after extracting the installation zip, move the properties file to the same location or the installation fails.
(Windows) Run the installer from the Administrative UI host system. Do not run the installer from a mapped network share or UNC path.
(Linux) Be sure that the required Linux libraries are installed to the Administrative UI host system. For more information, see Required Linux Libraries.
Important! (UNIX) Depending on your permissions, run the following command to add executable permissions to the directory that contains the installation media:
```
chmod -R+x directory
```
directory

Specifies the directory that contains the installation media.
(UNIX) If you execute the Administrative UI installer across different subnets, it can crash. Run the Administrative UI installer directly on the host system.

More information:

Locate the Installation Media

Installation Media Names

Required Linux Libraries

Certain library files are required for components operating on Linux operating environments. Failure to install the correct libraries can cause the following error:

java.lang.UnsatisfiedLinkError

If you are installing, configuring, or upgrading a Linux version of this component, the following libraries are required on the host system:

Red Hat 5.x:

compat–gcc-34-c++-3.4.6-patch_version.I386

libstdc++-4.x.x-x.el5.i686.rpm

Red Hat 6.x:

libstdc++-4.x.x-x.el6.i686.rpm

Additionally, for Red Hat 6.x (64-bit):

Note: All the RPM packages that are required for 64-bit Red Hat 6.x are 32-bit packages.

libXau-1.0.5-1.el6.i686.rpm

libxcb-1.5-1.el6.i686.rpm

compat-db42-4.2.52-15.el6.i686.rpm

compat-db43-4.3.29-15.el6.i686.rpm

libX11-1.3-2.el6.i686.rpm

libXrender-0.9.5-1.el6.i686.rpm

libexpat.so.1 (provided by expat-2.0.1-11.el6_2.i686.rpm)

libfreetype.so.6 (provided by freetype-2.3.11-6.el6_2.9.i686.rpm)

libfontconfig.so.1 (provided by fontconfig-2.8.0-3.el6.i686.rpm)

libICE-1.0.6-1.el6.i686.rpm

libuuid-2.17.2-12.7.el6.i686.rpm

libSM-1.1.0-7.1.el6.i686.rpm

libXext-1.1-3.el6.i686.rpm

compat-libstdc++-33-3.2.3-69.el6.i686.rpm

compat-db-4.6.21-15.el6.i686.rpm

libXi-1.3-3.el6.i686.rpm

libXtst-1.0.99.2-3.el6.i686.rpm

libXft-2.1.13-4.1.el6.i686.rpm

libXt-1.0.7-1.el6.i686.rpm

libXp-1.0.0-15.1.el6.i686.rpm

Upgrade the Administrative UI on Windows

Be sure that you extracted the prerequisite installer executable into the same directory that you extracted the Administrative UI installer. The installers must be in the same location so that the layout.properties file, included with the Administrative UI installation zip, is co-located with both executables.

If you move the prerequisite or Administrative UI installation media after extracting the zips, move the executables and the layout.properties file to the same location. Both executables and the layout.properties file must be co-located or the stand-alone installation fails.

Upgrading the Administrative UI requires that you run a prerequisite installer and the Administrative UI installer.

Follow these steps:

Exit all applications that are running.
Stop the application server that is hosting the Administrative UI.
Note: For more information about stopping the application server, see the r12.x Policy Server Installation Guide.
Run the following executable:
```
adminui-pre-req-version-cr-win32.exe
```
Follow the prerequisite installer prompts.
Run the following executable:
```
ca-adminui-version-cr-win32.exe
```
Follow the installer prompts and confirm the upgrade of the Administrative UI.
Review the installation settings and click Install.
The Administrative UI is upgraded.

Upgrade the Administrative UI on UNIX

You can upgrade the Administrative UI in GUI or console mode.

Follow these steps:

Exit all applications that are running.
Stop the application server that is hosting the Administrative UI.
Note: For more information about stopping the application server, see the r12.x Policy Server Installation Guide.
Open a shell and navigate to one of the following prerequisite installation executables:
```
adminui-pre-req-version-cr-linux.bin
adminui-pre-req-version-cr-sol.bin
```

Enter the command for the appropriate mode:

GUI Mode

./prerequisite_installation_media

Console Mode

./prerequisite_installation_media -i console

Follow the prerequisite installer prompts.
Open a shell and navigate to one of the following installation executables:
```
ca-adminui-version-cr-linux.bin
```
```
ca-adminui-version-cr-sol.bin
```
Enter the command for the appropriate mode:
GUI Mode
```
./installation_media
```
Console Mode
```
./installation_media -i console
```
Follow the prompts and confirm the upgrade of the Administrative UI.
Review the installation settings and click Install.
Start the application server that is hosting the Administrative UI.
Note: For more information about starting the application server, see the 12.52 Policy Server Installation Guide.

The Administrative UI is upgraded.

Upgrade the Administrative UI on UNIX Using a Console

Upgrading the Administrative UI requires that you run a prerequisite installer and the Administrative UI installer.

Follow these steps:

Exit all applications that are running.
Stop the application server that is hosting the Administrative UI.
Note: For more information about stopping the application server, see the r12.x Policy Server Installation Guide.
Open a shell and navigate to one of the following prerequisite installation executables:
```
adminui-pre-req-version-cr-linux.bin
adminui-pre-req-version-cr-sol.bin
```

Enter the following command:

./prerequisite_installation_media -i console

Follow the prerequisite installer prompts.
Open a shell and navigate to one of the following installation executables:
```
ca-adminui-version-cr-linux.bin
ca-adminui-version-cr-sol.bin
```
Enter the following command:
```
./installation_media -i console
```
Follow the prompts and confirm that the installer can upgrade the Administrative UI.
Review the installation settings and press Enter.
Start the application server that is hosting the Administrative UI.
Note: For more information about starting the application server, see the 12.52 Policy Server Installation Guide.

The Administrative UI is upgraded.