Release Notes › Policy Server Release Notes › Installation and Upgrade Considerations

Installation and Upgrade Considerations

Upgrade Information Page

In addition to the CA SiteMinder® Upgrade Guide, CA Support Online includes valuable upgrade information. For more information, see the CA 12.51 Upgrade Information page.

System Locale Must Match the Language of Installation and Configuration Directories

To install and configure a CA SiteMinder® component to a non-English directory, set the system to the same locale as the directory. Also, make sure that you installed the required language packages so the system can display and users can type localized characters in the installer screens.

For the details on how to set locale and required language packages, refer to respective operating system documents.

Local Fonts and Packages Required to Support International Language Versions of CA SiteMinder® Installers

To type local characters in international language versions of CA SiteMinder® installation and configuration programs in GUI mode, install fonts for that language on your operating environment.

For the RedHat Linux operating environment, download the packages shown in this document.

Java Virtual Machine Installation Error on Solaris can be Ignored (149886)

Symptom:

You are doing a console mode installation of a CA SiteMinder® product on a Solaris platform. The following error message displays: "Unable to install the Java Virtual Machine included with this installer."

Solution:

Ignore this error message. The error is a third-party issue and it has no functional impact.

Administrative UI and Internet Explorer 9 (149209)

If you are using Internet Explorer (IE) 9 to view the Administrative UI, run the Administrative UI in compatibility mode to submit the forms.

Consideration for Configuring the Web Services

If you are upgrading from 12.51 to 12.51x and you are using the authentication and authorization web services feature, update the policy store to add the new AuthAzServiceDefaultSettings ACO template for the web services.

Note: During the upgrade, the policy store schema requires no change.

To update the policy store, perform the following steps:

1. Stop the Policy Servers in your environment.
2. Do one of the following steps:
   • Import the smpolicy.xml file.
   • Import the smpolicy-secure.xml file.
3. Restart the Policy Servers.

For more information about upgrading from 12.x, see the CA SiteMinder® Upgrade Guide.

Installation Media Names

The following tables identify the installation executables for the following CA SiteMinder® components:

• Documentation
• Policy Server
• Administrative UI
• Report Server

Note: Information appears by platform. For more information about supported operating systems, see the 12.51 CA SiteMinder® Platform Support Matrix on the Technical Support site.

Documentation

The CA SiteMinder® bookshelf is available on the Support site. The bookshelf does not require an installer. For more information, see Locate the Bookshelf.

Policy Server

cr

Specifies the cumulative release number. The base 12.51 release does not include a cumulative release number.

Important! If you are running this wizard on Windows Server 2008, run the executable file with administrator permissions. Use these permissions even if you are logged in to the system as an administrator. For more information, see the release notes for your CA SiteMinder® component.

Administrative UI

cr

Specifies the cumulative release number. The base 12.51 release does not include a cumulative release number.

Important! If you are running this wizard on Windows Server 2008, run the executable file with administrator permissions. Use these permissions even if you are logged in to the system as an administrator. For more information, see the release notes for your CA SiteMinder® component.

Report Server

cr

Specifies the cumulative release number. The base 12.51 release does not include a cumulative release number.

Important! If you are running this wizard on Windows Server 2008, run the executable file with administrator permissions. Use these permissions even if you are logged in to the system as an administrator. For more information, see the release notes for your CA SiteMinder® component.

More information:

Locate the Platform Support Matrix

Password Policy Message and Active Directory

If you are upgrading to 12.51, the Password Services forms credential collector can present a password change message that users are not familiar with. If the following criteria are met, Active Directory users receive the password reuse message:

• The DisallowForceLogin registry key is enabled.

  Note: For more information, see the Policy Server Configuration Guide.

• An Active Directory user directory is bound to a password policy.
• The CA SiteMinder® password policy is not tracking password history.
• The Active Directory service is tracking password history and reuse.

This message states that a password change failed because an old password cannot be reused as new.

You can customize the password reuse message using the FCC properties template (smpwservicesUS–EN.properties). The template is located in web_agent_home\samples\forms.

web_agent_home

Specifies the web agent installation path.

Customized Password Change Messages

If Password Services is customized to send authentication failure messages based on CA SiteMinder® authentication reason codes, we recommend that you verify that your implementation handles all password message values (PasswordMsg) that the CA SiteMinder® SDK defines.

Password Services error handling is enhanced to:

• Better distinguish error codes that a user store returns for an authentication failure.
• Return a distinct CA SiteMinder® authentication reason code.

This enhancement can result in users receiving messages that they are unfamiliar with.

Certificate Revocation List Issuer

If you are upgrading to 12.51 and a CRL is stored in an LDAP directory service, consider the following items:

• CA SiteMinder® no longer requires that the issuer of the CRL is the same CA that issued the corresponding root certificate.
• CA SiteMinder® no longer performs this check. This behavior is consistent with the requirements for a text–based CRL.

Deprecated CA SiteMinder® Key Tool Options

If you are using key tool options in automated scripts, consider that the following options are deprecated:

• createDB

  This option is not being replaced and does not work with the accessLegacyKS argument. If a script uses this option:

  • The option executes to maintain backwards compatibility, but does not create a smkeydatabase.
  • A message states that the option is deprecated.

  Note: If a script also attempts to verify that a smkeydatabase was created successfully, the script fails. A smkeydatabase directory does not exist in an 12.51 Policy Server installation.

• deleteDB

  This option is deprecated. The removeAllCertificateData replaces this option. If a script uses the deleteDB option:

  • The option executes to maintain backwards compatibility. All certificate data in the certificate data store, not a smkeydatabase, is removed.
  • A message states that the option is deprecated.
• changePassword

  This option is not being replaced. If a script uses this option:

  • The option executes to maintain backwards compatibility, but does not change a password.
  • A message states that the option is deprecated.

Upgrading a Policy Store

In previous releases, you used the smobjimport utility to import an upgrade CA SiteMinder® data interchange format (smdif) file. Importing an upgrade file, instead of the smpolicy file (smpolicy.smdif), prevented existing default objects that were modified from being overwritten.

This release no longer requires an upgrade file. You use the XPSInstall utility to import the smpolicy.xml file. When you import this file as part of an upgrade, it does not overwrite existing default objects that were modified.

Note: For more information about upgrading a policy store, see the CA SiteMinder® Upgrade Guide.

Policy Server Upgrade Requirement for 12.5 GA and 12.5 CR1

The format of certificates that are stored in the 12.51 policy store is different from certificates that are stored in Policy Server r12.5 GA and Policy Server r12.5 CR.

Therefore, export certificates that were imported into the Policy Store before CA SiteMinder® r12.5 CR2 before you upgrade and then reimport them.

Follow these steps:

1. Before you upgrade the Policy Server to 12.51, export the certificates using the Administrative UI or smkeytool.
2. After you successfully export the certificates, delete the certificates from the Policy Store using Administrative UI or smkeytool.
3. Complete the upgrade procedure to Policy Server 12.51.
4. Import the certificates (that were exported in Step 1) using the Administrative UI or smkeytool.

Considerations for Upgrading r6.x to r12.x

If your Policy Server and policy store are operating in mixed-mode during an upgrade to 12.51, the following error message appears when you start the Policy Server:

[8114/21][Fri Oct 15 2010 09:10:26][CA.XPS:LDAP0014][ERROR] Error occurred during "Modify" for
xpsParameter=CA.XPS::$PolicyStoreID,ou=XPS,ou=policysvr4,ou=siteminder,ou=netegrity,dc=PSRoot",text: Object
class violation

[8114/21][Fri Oct 15 2010 09:10:26][CA.XPS:XPSIO024][ERROR] Save Policy Store ID failed.

This message is expected behavior and does not affect the CA SiteMinder® environment.

This message occurs because the r6.x policy store is not upgraded. Part of the upgrade process includes importing the policy store data definitions. The error appears in the CA SiteMinder® Policy Server log because the data definitions are not available in the policy store.

Considerations for Existing LDAP User Directory Connections Over SSL

Configuring an LDAP user directory connection over SSL requires that you configure CA SiteMinder® to use your certificate database files.

The Policy Server requires that the certificate database files be in the Netscape cert8.db file format. Use the Mozilla Network Security Services (NSS) certutil application installed with the Policy Server to convert existing cert7.db certificate database files to cert8.db format.

Note: The following procedure details the specific options and arguments to complete the task. For a complete list of the NSS utility options and arguments, refer to the Mozilla documentation on the NSS project page.

Important! 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.

To convert the certificate database file

1. From a command prompt, navigate to the Policy Server installation bin directory.

   Example: C:\Program Files\CA\SiteMinder\bin

   Note: Windows has a native certutil utility. Verify that you are working from the Policy Server bin directory, or you can inadvertently run the Windows certutil utility.

2. Enter the following command:

   certutil  -L  -d certificate_database_directory [-p prefix_name]  -X
   

   -d certificate_database_directory

   Specifies the directory that contains the certificate database files to convert.

   -p prefix_name

   (Optional) Specifies any prefix used when creating the existing cert7.db file (for example, my_cert7.db).

   Certutil converts the existing cert7.db file to cert8.db format.

Considerations for Localized Installations

Consider the following limitations before installing the Policy Server on a system with a non–English operating system:

• The Administrative UI cannot be installed in any mode (silent, command line, GUI) in a directory with a name that uses multi–byte characters.
• Windows 2008 lets you set different regional and language settings for individual user accounts. However, the System and other service accounts must be set to use the default Japanese locale or the component you are installing will not initialize.

  To set the locale for the System or other service accounts, see the Microsoft documentation.

ETPKI Library Installation

The Policy Server and Web Agent installations include a CA ETPKI library.

For Windows operating environments, if a CA ETPKI library exists on the machine to which you are installing the Policy Server or Web Agent, the installer upgrades the existing ETPKI library to the version shipped with the component. The CA ETPKI library remains in its current location.

For UNIX operating environments, the installer will install the CA ETPKI library to the installation_location/ETPKI directory, even if another CA ETPKI library exists elsewhere on the UNIX file system.

Upgrading a Collocated Policy Server and Web Agent

Valid on Windows

Symptom:

If a Policy Server and Web Agent are installed to the same host system, after you upgrade the Policy Server, the IIS web server fails to start and an error is logged in the Event Viewer.

Solution:

Upgrade the Web Agent. The IIS web server starts after you upgrade the Web Agent.

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.51 files use the .new extension: For example, the JVMOptions.txt file from the previous version remains untouched. The installer creates an 12.51 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.

Connection Between PS on UNIX and SQL Server

When attempting to connect a SiteMinder Policy Server on Red Hat or Solaris to a Microsoft SQL Server 2008 database, you should correctly define the paths to the TraceFile, TraceDll and InstallDir parameters specified in the [ODBC] section of the system_odbc.ini file. Failure to do so may result in connectivity errors.

Character Restriction for Passwords in Installations (72360)

When installing the Policy Server, the CA Report Server, and the Administrative UI, you are asked to specify passwords for various components. Consider the following:

Policy Server

When entering password information, do not use the following characters as they are reserved or restricted:

• (Windows only) A percent sign (%)
• (Reserved by InstallAnywhere) A dollar sign ($)
• (UNIX only) An apostrophe (’)
• (UNIX only) Quotation marks (“”)

CA Report Server

When entering password information, do not use the following characters as they are reserved or restricted:

• (Reserved by InstallAnywhere) A dollar sign ($)
• (UNIX only) An apostrophe (’)
• (UNIX only) Quotation marks (“”)

Administrative UI

When entering password information, do not use the following characters as they are reserved or restricted:

• (UNIX only) An apostrophe (’)
• (UNIX only Quotation marks (“”)

Distributed CA Directory Server Policy Store

If you are using multiple DSAs to function as a policy store, ensure that host information of the router DSA is listed first in the Policy Server Management Console. If you do not list the router DSA host information first, an error occurs when you attempt to install the policy store data definitions.

Note: For more information on configuring CA Directory Server as a policy store, refer to the Policy Server Installation Guide.

Importing Event Handler Libraries

Consider the following before upgrading a Policy Sever to 12.51:

• If the Policy Server Management Console Advanced tab does not contain event handler libraries, the XPSAudit event handler library (XPSAudit.dll) is added to the Event Handlers field. No further action is required.
• If the Policy Server Management Console Advanced tab does contain event handler libraries, complete the following after upgrading the Policy Server:

1. Open the Policy Server Management Console and click the Advanced Tab.
2. In the Event Handlers field, replace the path to the current event handler library with the path to the XPSAudit event handler library.

   Note: The default location of the XPSAudit event handler library is policy_server_home\bin.

   policy_server_home

   Specifies the Policy Server installation path.

3. Click Apply.

   The path to the event handler library is saved. The Event Handlers field appears disabled.

   Note: By default, the only event handler library that appears in the Advanced tab is XPSAudit.dll.

4. Use the XPSConfig utility to set additional event handler libraries, previously used or otherwise, to the XPSAudit list.

   Note: More information on using the XPSConfig utility to set event handler libraries exists in the Policy Server Administration Guide.

MDAC Versions

It is required that the MDAC versions installed on the client and server sides are compatible.

Note: More information exists in the Microsoft MDAC documentation.

Multi-Mastered LDAP Policy Stores

LDAP directories using multi-master technology may be used as CA SiteMinder® policy stores. The following configuration is recommended when configuring an LDAP policy store in multi-master mode:

• A single master should be used for all administration.
• A single master should be used for key storage.

  This master does not need to be the same as the master used for Administration. However, we recommend that you use the same master store for both keys and administration. In this configuration, all key store nodes should point to the master rather than a replica.

  Note: If you use a master for key storage other than the master for administration, then all key stores must use the same key store value. No key store should be configured to function as both a policy store and a key store.

• All other policy store masters should be set for failover mode.

Due to possible synchronization issues, other configurations may cause inconsistent results, such as policy store corruption or Agent keys that are out of sync.

Contact CA SiteMinder® Support for assistance with other configurations.

Multi–Mastered LDAP User Store Support Limitations (53677)

The multi–mastered LDAP enhancement has the following limitations:

• The Policy Server only supports multi–mastered user stores in a backup capacity. Because Password Services makes frequent writes to the user store, you cannot simultaneously update user information in multiple master instances. In addition, the LDAP implementation could produce out–of–date information or data loss due to delayed replication.
• Multi–mastered support does not extend to custom code such as custom authentication schemes.

Compatibility with Other Products

To ensure interoperability if you use multiple products, such as CA IdentityMinder and CA SiteMinder WSS check the Platform Support Matrices for the required releases of each product. The platform matrices exist on the Technical Support site.

Updated snmptrap File

This release includes an updated snmptrap.conf file. Before installation, back up and save the original snmptrap.conf file, located in siteminder_installation\config.

Windows Considerations

The following considerations apply to supported Windows operating environments:

DEP Error during Policy Server Installation

Symptom:

A Data Execution Prevention (DEP) error can prevent the Policy Server from installing on Windows 2008 SP2.

Solution:

1. Configure DEP for essential Windows programs and services only.
2. Run the Policy Server installer.

To configure DEP for essential programs and services

1. Right–click My Computer and select Properties.

   The System Properties dialog appears.

2. Click Advanced.

   The Advanced tab opens.

3. Under Performance, click Settings.

   The Performance Options dialog appears.

4. Click Data Execution Prevention and select Turn on DEP for essential Windows programs and services only.
5. Click OK.

   A message prompts you to restart the system.

Note: After you have successfully installed the Policy Server, you can revert the DEP settings for all programs and services.

Windows Server 2008 System Considerations

For Windows Server 2008, the User Account Control feature helps prevent unauthorized changes to your system. When the User Account Control feature is enabled on the Windows Server 2008 operating environment, prerequisite steps are required before doing any of the following tasks with a CA SiteMinder® component:

• Installation
• Configuration
• Administration
• Upgrade

Note: For more information about which CA SiteMinder® components support Windows Server 2008, see the CA SiteMinder® Platform Support matrix.

To run CA SiteMinder® installation or configuration wizards on a Windows Server 2008 system

1. Right–click the executable and select Run as administrator.

   The User Account Control dialog appears and prompts you for permission.

2. Click Allow.

   The wizard starts.

To access the CA SiteMinder® Policy Server Management Console on a Windows Server 2008 system

1. Right–click the shortcut and select Run as administrator.

   The User Account Control dialog appears and prompts you for permission.

2. Click Allow.

   The Policy Server Management Console opens.

To run CA SiteMinder® command–line tools or utilities on a Windows Server 2008 system

1. Open your Control Panel.
2. Verify that your task bar and Start Menu Properties are set to Start menu and not Classic Start menu.
3. Click Start and type the following in the Start Search field:

   Cmd
   

4. Press Ctrl+Shift+Enter.

   The User Account Control dialog appears and prompts you for permission.

5. Click Continue.

   A command window with elevated privileges appears. The title bar text begins with Administrator:

6. Run the CA SiteMinder® command.

More information:

Contact CA Technologies

Deploying CA SiteMinder® Components

If you are deploying CA SiteMinder® components on Windows 2008 SP2, we recommend installing and managing the components with the same user account. For example, if you use a domain account to install a component, use the same domain account to manage it. Failure to use the same user account to install and manage a CA SiteMinder® component can result in unexpected behavior.

Solaris Considerations

The following considerations apply to Solaris.

Solaris 10 Support

The Policy Server and Web Agent are certified for global and non-global zones.

Note: More information on Solaris 10 support exists in the Policy Server Installation Guide.

Errors in the SMPS Log due to a gethostbyname() Error (54190)

Network connectivity errors appear in the smps log when gethostbyname() is called. These errors appear even though the directories are available on the network. This was a Solaris issue, which according to Sun bug ID 4353836, has been resolved.

Sun lists the following patches for Solaris 9:

Solaris 9

• 112874-16 (libc)
• 113319-12 (libnsl)
• 112970-05 (libresolv)
• 115545-01 (nss_files)
• 115542-01 (nss_user)
• 115544-01 (nss_compat)

Upgrading a Solaris Policy Server (57935)

Symptom:

If your license file is older than January 2005, the Policy Server may experience problems reading the license file after an upgrade. You may receive a message stating that a valid end-user license cannot be found.

Solution:

Contact Technical Support, and request a new license file.

Report Server Required Patch Clusters

The Policy Server Installation Guide contains the system requirements required to install the Report Server. SAP BusinessObjects Enterprise provides additional patch specifications. Before installing the Report Server:

1. Go to temporary_location/docs.

   temporary_location

   Specifies the location to which you copied the installation media.

2. Open SAP BusinessObjects Enterprise XI 3.1 SP3 for Solaris – Supported Platforms (supported platforms SP3 - Solaris.pdf).
3. Review the Solaris 9 or 10 patch requirements.

Use this resource for Solaris 9 and 10 patch requirements only. This document also provides supported operating system and hardware requirements that CA SiteMinder® does not support. For supported operating systems, see the CA SiteMinder® 12.51 Platform Support Matrix. For system requirements, see the Policy Server Installation Guide.

Red Hat Enterprise Linux AS and ES Considerations

The following considerations apply to Red Hat Enterprise Linux AS and ES.

Red Hat Enterprise Linux AS Requires Korn Shell (28782)

A Policy Server installed on Red Hat AS requires the Korn shell. If you do not install a Korn shell on Red Hat AS, you cannot execute the commands that control the Policy Server from a command line, such as start-all and stop-all.

Excluded Features on Red Hat Enterprise Linux AS

The following features are not supported by the Policy Server on Red Hat AS:

• Safeword authentication scheme
• SiteMinder Test Tool

Apache 2.0 Web Server and ServletExec 5.0 on Red Hat Enterprise Linux AS (28447, 29518)

To use Apache 2.0 Web Server and ServletExec 5.0 on Red Hat AS

1. Run the ServletExec 5.0 AS installer against Apache 1.3.x.

   The ServletExec AS Java instance is created.

2. Run ServletExec and Apache 1.3.x, and make sure you can run /servlet/TestServlet.
3. Shutdown Apache 1.3.x, but leave ServletExec running.
4. Using anonymous FTP, access ftp://ftp.newatlanta.com/public/servletexec/4_2/patches and download the latest zip.
5. Extract the following from the zip:

   mod_servletexec2.c
   

6. Edit the httpd.conf file of your HP-Apache 2.x so that it contains the necessary ServletExec-specific directives.

   Note: The directives are also present in the httpd.conf file of your Apache 1.3.x if you allowed the ServletExec installer to update the httpd.conf during installation. For more information on editing the httpd.conf file, refer to the New Atlanta Communication ServletExec documentation.

7. Start Apache 2.x.
8. Test the Web Server with ServletExec by accessing:

   /servlet/TestServlet
   

Report Server Required Patch Clusters

The Policy Server Installation Guide contains the system requirements required to install the Report Server. SAP BusinessObjects Enterprise provides additional patch specifications. Before installing the Report Server:

1. Go to temporary_location/docs.

   temporary_location

   Specifies the location to which you copied the installation media.

2. Open SAP BusinessObjects Enterprise XI 3.1 SP3 for Linux – Supported Platforms (supported platforms SP3 - Linux.pdf).
3. Review the Red Hat 5 patch requirements.

Use this resource for Red Hat 5 requirements only. This document also provides supported operating system and hardware requirements that CA SiteMinder® does not support. For supported operating systems, see the CA SiteMinder® 12.51 Platform Support Matrix. For system requirements, see the Policy Server Installation Guide.