Upgrade Policy Server

This content describes how to upgrade a 12.5x or later Policy Server to 12.7.
casso127
This content describes how to upgrade a 12.5x or later Policy Server to 12.7.
The 12.7 Policy Server is a 64-bit executable and requires a supported 64-bit operating system. You can therefore only upgrade an existing Policy Server running on Windows Server 2012 R2 or Red Hat Enterprise Linux 6. If your Policy Server is running on another operating system, perform a
fresh installation
on Windows Server 2012 R2, Red Hat Enterprise Linux 6, or Red Hat Enterprise Linux 7. If you must install a new 12.7 Policy Server, the 12.7 Policy Server can point it to an existing policy store. The store has to include a CDS or have been extended to include a CDS.
2
The following figure shows the general steps of the upgrade:
Upgrade Policy Server to 12.6
Upgrade Policy Server to 12.6
Complete Prerequisite Tasks
Before you upgrade a Policy Server, complete the prerequisite tasks.
Install a 64-Bit JRE
Verify that a supported 64-bit JRE is installed on the Policy Server host system. See the Platform Support Matrix for more information.
Install Required Korn Shell (ksh) Package on Linux
Verify that the library required to support the Korn shell (ksh), which is required during Policy Server installation and upgrade is present.
Support Unlimited Key Strength in the Java Cryptography Extension Package
Verify that JRE supports unlimited key strength in the Java Cryptography Extension (JCE) package.
For JDK 1.8_151 and later, perform the following steps:
  1. Navigate to the 
    jdk_home
    /jre/lib/security directory and open the 
    java.security
     file.
  2. Uncomment the following line:
    crypto.policy=unlimited
  3. Save the file.
For the other previous versions of JDK, perform the following steps:
  1. Locate the JCE package for your operating system from the Oracle website.
  2. Download the unlimited JCE package for the Java version that is supported by 
    CA Single Sign-On
  3. Navigate to the 
    jdk_home
    \jre\lib\security directory on your system and apply the patch to the following files:
    • local_policy.jar
    • US_export_policy.jar
jdk_home
 specifies the location of the Java installation.
Correct Integrity Errors in Your Policy Store
To prevent upgrading older policy stores that contain integrity errors, run the XPSSweeper utility in analysis mode (using the -a command option). 
Run the tool on only one Policy Server at time.
Disable XML Signature Wrapping Checks Before a Policy Server Upgrade
SAML 2.0 artifact transactions fail in federation (legacy or partnership) deployments after you upgrade the Policy Server at the Service Provider.
The following conditions result in failed transactions:
  • CA Single Sign-On
     federation is deployed is at the Service Provider site.
  • SAML 2.0 HTTP-Artifact SSO is configured.
  • Signature verification at the Service Provider is configured for the assertion or the artifact resolve response.
  • The Policy Server setting that prevents XML signature wrapping attacks is enabled.
When the Policy Server tries to verify that the signature of the artifact response, the SSO transaction fails.
To prevent artifact SSO from failing, temporarily turn off the signature vulnerability check. Disable the check after you upgrade the Policy Server at the Service Provider site but before you put the Policy Server into service.
Follow these steps:
  1. Navigate to the xsw.properties file. Locate the file in the following directory:
    siteminder_install_dir
    \config\properties\xsw.properties
    siteminder_install_dir 
    is the location where you installed the Policy Server.
  2. Open the file in a text editor, and set the DisableXSWCheck to true (DisableXSWCheck=true). Setting the value to true disables the vulnerability check.
  3. After the entire deployment is at version 12.52 or later, and the Policy Server is running, return the DisableXSWCheck setting to false (DisableXSWCheck=false). Setting the value to false enables the signature vulnerability check.
Verify the Back Channel User Name Is Unique for Each SAML Partnership
During an HTTP-Artifact single sign-on transaction, the asserting party returns the assertion to the relying party over a secured back channel. You can require an entity to authenticate to access the back channel. If you select Basic as the authentication method for the back channel, a user name is needed.
Before you upgrade, verify that each federated partnership in the same SAML profile uses a unique user name for the incoming back channel. Each SAML 1.x partnership must have a unique incoming back channel user name. Each SAML 2.0 partnership must have a unique incoming back channel user name.
  A SAML 1.x partnership
can
share an incoming back channel user name with a SAML 2.0 partnership but it is not recommended.
If there are partnerships of the same protocol that share an incoming back channel user name, do the following steps before you upgrade.
  1. Deactivate one of the partnerships.
  2. Change the back channel user name that is defined in that partnership.
  3. Inform the remote partner of the change.
  4. Reactivate the partnership.
Locate Installation Media for Upgrades 
To locate and download installation media, go to the CA Support site.
Upgrade a Policy Server on Windows
This section describes how to upgrade a Policy Server on Windows.
The 12.7 Policy Server is a 64-bit executable and requires Windows Server 2012 R2. You cannot upgrade the 12.52 SP2 Policy Server in place in the Program Files (x86) directory. The 12.7 Policy Server is a 64-bit application and only 32-bit applications belong in this directory. If upgrading from releases earlier than 12.52 SP2 or if your 12.52 SP2 Policy Server is installed under the Program Files (x86) directory, install a new Policy Server on Windows Server 2012 R2.
Follow these steps:
  1. Start the Policy Server. The Policy Server
    must be running
    to execute the upgrade. 
    The installer stops the Policy Server before starting to upgrade files. This prevents agents from contacting it while the upgrade is in process.
    Shut down all instances of the Policy Server Management Console and OneView Monitor. 
    In silent mode upgrade of Policy Server, if the Policy Server is not running, the upgrade continues with errors. Start the Policy Server to avoid errors and proceed with upgrade.
  2. Exit all other applications that are running.
  3. Navigate to the installation media.
  4. Double-click the installer executable.
  5. Follow the prompts.
    : The installer runs the Upgrade Readiness utility to identify potential issues with custom components. If no issues are found, the utility runs silently. If issues are found, the installer displays the screen, which lists the components that you should remove or upgrade (to a 64-bit version) after the upgrade completes. For more information about the Upgrade Readiness Check Utility and to learn how to run it after the upgrade, see Manually Check for Issues with Custom Binaries and Authentication Schemes.
  6. Review the installation settings and click
    Install
    .
    The installer stops the Policy Server and installs the new Policy Server and Policy Server components. Consider the following actions that occur during the Policy Server upgrade:
    On the Install Complete screen, specify whether the installer should restart the system or not and click Done.
    • The installer moves registry entries from HKEY_LOCAL_MACHINE\SOFTWARE\Netegrity to HKEY_LOCAL_MACHINE\SOFTWARE\Netegrity.
    • For ODBC policy stores, the installer moves all registry entries related to
      CA Single Sign-On
      drivers under HKEY_LOCAL_MACHINE\SOFTWARE\Netegrity\ODBC\ODBC.INI to HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI.
    • The installer backs up the registry files in
      PS_install_dir
      \install_config_info for future reference.
    • The installer backs up configuration files in
      PS_install_dir
      \config\,
      PS_install_dir
      \monitor\, and
      PS_install_dir
      \db\
    The Policy Server is upgraded.
If the Upgrade Readiness utility identified potential issues with custom components, remove or upgrade them to a 64-bit version before restarting the Policy Server. Failure to do so is likely to cause errors. Refer to the utility report (UpgradeReadinessCheck
_timestamp
.txt) located in
PS_install_dir\
install_config_info\.
Policy Server includes the binaries required by the SessionLinker. You do not need to install SessionLinker separately.
Upgrade a Policy Server on UNIX
You can upgrade a Policy Server on a Linux platform in GUI or Console mode.
The 12.7 Policy Server is a 64-bit executable and requires a supported 64-bit operating system. You can therefore only upgrade an existing UNIX Policy Server running on Red Hat Enterprise Linux 6. If your existing Policy Server is running on another operating system, perform a on Red Hat Enterprise Linux 6 or Red Hat Enterprise Linux 7.
Before you upgrade, verify the following items:
  • Ensure that the user account upgrading the Policy Server has 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.
  • If you execute the Policy Server across different subnets, it can crash. Run the Policy Server installer directly on the host system.
  • 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 Server using a root user.
  • If you perform the upgrade as a non-root user, 'Server instance SiteMinder not found' error message is displayed. This is because, SmCommand fails to work with non-root user privileges. 
    Before you perform upgrade, locate the following files in the /tmp folder and verify if they have root or smuser permissions:
    • GCL-siteminder-A.pipe
    • GCL-siteminder-B.pipe
    • GCL-SiteMinder.sem
    If the files have root permissions, they fail to execute with non-root user. To perform upgrade, you must modify the permissions of these files to non-root user. 
    Alternately, do the following:
 
    1. Delete the files- GCL-siteminder-A.pipe, GCL-siteminder-B.pipe, and GCL-SiteMinder.sem.
    2. Stop the Policy Server using the following command:
      ./stop-all
    3. Restart the Policy Server using the following command with smuser. Do not use sudo command.
      ./start-all
Upgrade a Policy Server on Linux Using GUI Mode
Follow these steps:
  1. Start the Policy Server. The Policy Server
    must be running
    to execute the upgrade.
    The installer stops the Policy Server before starting to upgrade files. This prevents agents from contacting it while the upgrade is in process. 
  2. Shut down all instances of the Policy Server Management Console and OneView Monitor.
  3. Exit all other applications that are running.
  4. Open a ksh shell and navigate to the Policy Server installation directory.
  5. Enter the following command: (There must be a space between the periods.).
    . ./ca_ps_env.ksh
  6. Open a shell and navigate to the installation executable.
  7. Enter the following command:
    ./
    installation_media
    installation_media
     specifies the Policy Server installer executable.
  8. Follow the prompts.
    : The installer runs the Upgrade Readiness utility to identify potential issues with custom components. If no issues are found, the utility runs silently. If issues are found, the installer displays the
    "
    Important: Upgrade Readiness Check
    "
    screen, which lists the components that you should remove or upgrade (to a 64-bit version) after the upgrade completes. For more information about the Upgrade Readiness Check Utility and to learn how to run it after the upgrade, see Manually Check for Issues with Custom Binaries and Authentication Schemes.
  9. Review the installation settings and click
    Install
    .
    The installer stops the Policy Server and installs the new Policy Server and Policy Server components.
    The Policy Server is upgraded.
  10. On the Install Complete screen, click Done.
    • The installer backs up the registry files in 
      PS_install_dir
      \install_config_info for future reference.
    • The installer backs up configuration files in 
      PS_install_dir
      /config/, 
      PS_install_dir
      /monitor/, and 
      ps_install_di/
      \db/
  11. Execute the following script in a ksh shell from the installation directory. There must be a space between the periods.
    . ./ca_ps_env.ksh
If the Upgrade Readiness utility identified potential issues with custom components, remove or upgrade them to a 64-bit version before restarting the Policy Server. Failure to do so is likely to cause errors. Refer to the utility report (UpgradeReadinessCheck_timestamp.txt)  located in
PS_install_dir/
install_config_info/.
Upgrade a Policy Server on Linux Using a Console
Follow these steps:
  1. Start the Policy Server. The Policy Server
    must be running
    to execute the upgrade.
    : The installer stops the Policy Server before starting to upgrade files. This prevents agents from contacting it while the upgrade is in process.
  2. Shut down all instances of the Policy Server Management Console and OneView Monitor.
  3. Exit all other applications that are running.
  4. Open a ksh shell and navigate to the Policy Server installation directory.
  5. Enter the following command: (There must be a space between the periods.)
    . ./ca_ps_env.ksh
  6. Navigate to the installation executable.
  7. Enter the following command:
    ./installation_media
    -i console
    installation_media
     specifies the Policy Server installation executable.
  8. Follow the prompts.
    : The installer runs the Upgrade Readiness Check utility to identify potential issues with custom components. If no issues are found, the utility runs silently. If issues are found, the installer displays the
    "
    Important: Upgrade Readiness Check
    "
    screen, which lists the components that you should remove or upgrade (to a 64-bit version) after the upgrade completes. For more information about the Upgrade Readiness Check Utility and to learn how to run it after the upgrade, see Manually Check for Issues with Custom Binaries and Authentication Schemes.
  9. Review the installation settings and click
    Install
    .
    The installer stops the Policy Server and installs the new Policy Server and components. Consider the following actions that occur during the Policy Server upgrade:
    On the Install Complete screen, click Done.
    • The installer backs up the registry files in
      PS_install_dir
      \install_config_info for future reference.
    • The installer backs up configuration files in
      PS_install_dir
      /config/,
      PS_install_dir
      /monitor/, and
      ps_install_di/
      \db/
    The Policy Server is upgraded.
  10. Execute the following script in a ksh shell from the installation directory. There must be a space between the periods.
    . ./ca_ps_env.ksh
If the Upgrade Readiness utility identified potential issues with custom components, remove or upgrade them to a 64-bit version before restarting the Policy Server. Failure to do so is likely to cause errors. Refer to the utility report (UpgradeReadinessCheck_timestamp.txt)  located in
PS_install_dir/
install_config_info/.
Update Configuration Files
During upgrade, the installer takes the following actions with your configuration (.txt and .properties) files:
  • Preserves your existing configuration files in the following directories:
    • PS_install_dir
      \config 
    • PS_install_dir
      \config\properties
  • Writes new configuration files with a
    .new
    extension
Follow these steps:
  1. Compare the existing files with the new files.
  2. For each original file with customized settings, do the following steps:
    1. Copy the customized settings to the .new file.
    2. Rename the original file (for example, by adding a
      .old
      extension).
    3. Rename the .new file to the name of the original file (by removing the
      .new
      extension.
Update the JVMOptions File with Customized Parameters
During a Policy Server upgrade, the existing JVMOptions.txt file is renamed to JVMOptions.txt.backup and a new JVMOptions.txt file is created. If the existing file includes customized parameters, add these customized parameters to the new file.
Recompile Custom Server-Side Code
All custom server-side native code must be recompiled because the Policy Server is now a 64-bit application.