Installation and Upgrade Guides › SiteMinder Upgrade Guide › Upgrading from CA SiteMinder® r6.x › How to Migrate from r6.x › Upgrade an r6.x Policy Server

Upgrade an r6.x Policy Server

The following sections detail how to upgrade an r6.x Policy Server on Windows and UNIX.

Before You Upgrade

Consider the following items before you upgrade a Policy Server:

• 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 migrating content to the certificate data store.
• (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 being upgraded from your environment. Removing the Policy Server prevents Web Agents from contacting the Policy Server during the upgrade.
• Shut down all Policy Server Management Console instances.
• During the upgrade, leave the policy store check box on the configuration wizard cleared to preserve your existing policy store. However, the configuration wizard prompts you for the encryption key for the advanced authentication server. This key is stored on each Policy Server, but all Policy Servers require the same key.
• (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 installer across different subnets, it can crash. Run the installer directly on the Policy Server host system.

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 packages 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
• libidn.so.11.rpm
• ncurses

Red Hat 6.x:

• libstdc++-4.x.x-x.el6.i686.rpm
• libidn-1.18-2.el6.i686
• libXext.i686.rpm
• libXrender.i686.rpm
• linXtst.i686.rpm
• libidn.so.11.rpm
• ncurses

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

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
• libstdc++.i686.rpm
• compat-libtermcap.rpm
• libidn.i686.rpm
• ncurses

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

Windows

Follow these steps:

1. Exit all applications that are running.
2. Stop the Policy Server that you want to upgrade.
3. Double–click installation_media.

   installation_media

   Specifies the Policy Server installation executable.

4. Considering the following items when running the installer:
   • The installer prompts you to select CA SiteMinder® components. When selecting components:
     • Reconfigure any components that had been previously configured for the environment. Be sure to select the respective components.
     • During the upgrade, leave the policy store check box on the configuration wizard cleared to preserve your existing policy store. You manually upgrade an existing policy store. However, the configuration wizard prompts you for the encryption key for the advanced authentication server. This key is stored on each Policy Server, but all Policy Servers require the same key.
     • If you are upgrading another (nth) Policy Server, use the same encryption key for the Advanced Authentication server that you used previously.
   • 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.

   • If you cut and paste path information into the wizard, enter a character to enable the Next button.
5. Review the installation settings and click Install.

   The Policy Server is upgraded. The selected components are configured for use with the Policy Server.

6. Enable the advanced authentication server for the Policy Server that you are upgrading.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

UNIX GUI

Follow these steps:

1. Exit all applications that are running.
2. Stop the Policy Server that you want to upgrade.
3. 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.

4. Open a shell and navigate to the installation executable.
5. Enter the following command:

   ./installation_media
   

   installation_media

   Specifies the Policy Server installation executable.

6. Considering the following items when running the installer:
   • The installer prompts you to select CA SiteMinder® components. When selecting components:
     • Reconfigure components that had been previously configured for the environment. Be sure to select the respective components.
     • During the upgrade, leave the policy store check box on the configuration wizard cleared to preserve your existing policy store. You manually upgrade an existing policy store. However, the configuration wizard prompts you for the encryption key for the advanced authentication server. This key is stored on each Policy Server, but all Policy Servers require the same key.
     • If you are upgrading another (nth) Policy Server, use the same encryption key for the Advanced Authentication server that you used previously.
   • 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.

   • If you cut and paste path information into the wizard, enter a character to enable the Next button.
7. Review the installation settings and click Install.

   The Policy Server is upgraded. The selected components are configured for use with the Policy Server.

   Note: The upgrade can take several minutes.

8. Click Done.
9. 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.

10. Enable the advanced authentication server for the Policy Server that you are upgrading.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

UNIX Console

Follow these steps:

1. Exit all applications that are running.
2. Stop the Policy Server that you want to upgrade.
3. 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.

4. Open a shell and navigate to the installation executable.
5. Enter the following command:

   ./installation_media -i console
   

   installation_media

   Specifies the Policy Server installation executable.

6. 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 that are separated with a comma (,) to select one or more components. Enter only a comma to select none of the features. When selecting components:
     • Reconfigure components that had been previously configured for the environment. Be sure to select the respective components.
     • During the upgrade, leave the policy store check box on the configuration wizard cleared to preserve your existing policy store. You manually upgrade an existing policy store. However, the configuration wizard prompts you for the encryption key for the advanced authentication server. This key is stored on each Policy Server, but all Policy Servers require the same key.
     • If you are upgrading another (nth) Policy Server, use the same encryption key for the Advanced Authentication server that you used previously.
   • 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.

7. Review the installation settings and press Enter.

   The Policy Server is upgraded. The selected components are configured for use with the Policy Server.

   Note: The upgrade can take several minutes.

8. Press Enter.
9. Click Done.
10. 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.

11. Enable the advanced authentication server for the Policy Server that you are upgrading.

More information:

Troubleshoot a Policy Server Upgrade

Installation Media Names

Enable the Advanced Authentication Server

Enable the advanced authentication server as part of configuring your Policy Server.

Follow these steps:

1. Start the Policy Server configuration wizard.
2. Leave all the check boxes in the first screen of the wizard cleared.
3. Click Next.
4. Create the master encryption key for the advanced authentication server.

   Note: If you are installing another (nth) Policy Server, use the same encryption key for the Advanced Authentication server that you used previously.

5. Complete the rest of the Policy Server configuration wizard.

   The advanced authentication server is enabled.

Modify Customized Files

During a Policy Server upgrade, the installer creates new versions of certain files. The installer creates the following files in the policy_server_home/config directory:

• conapi.conf
• JVMOptions.txt
• profiler_templates
• siteminder.conf
• SMocsp.sample.conf
• SmSWEC.cfg
• smtracedefault.txt
• snmp.conf
• snmptrap.conf
• trace.conf

The installer creates the following files in the policy_server_home/properties directory:

• AMAssertionGenerator.properties
• AssertionGeneratorFramework.properties
• cdslog4j.properties
• EntitlementGenerator.properties
• FederationAttributeConfig.properties
• InfoCard.properties
• JSAMLAssertionStrings.properties
• JSAMLProtocolStrings.properties
• log4j.properties
• LoggerConfig.properties
• logging.properties
• openformatexpression.conf
• scriptActiveExpConfig.properties
• smkeydatabase.properties
• WebServiceConfig.properties
• xsw.properties

These 12.52 SP1 files use the .new extension: For example, the JVMOptions.txt file from the previous version remains untouched. The installer creates an 12.52 SP1 version of the JVMOptions.txt file that is named JVMOPtions.new.

If the original file included customized settings, be sure to modify the .new file with your customized settings. Rename the .new file with the extension from the original file.

For example, if you had custom settings in your JVMOptions.txt file, copy those changes to JVMOptions.txt.new. Rename the JVMOptions.txt.new to JVMOptions.txt.

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:

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.