Installation and Upgrade Guides › SiteMinder Upgrade Guide › Upgrading from r6.x › How to Migrate from r6.x

How to Migrate from r6.x

Follow these steps to complete a migration from r6.x to 12.52:

1. Review the installation and upgrade considerations in the Policy Server Release Notes.
2. Download the policy store schema files.
3. Extend the r6.x policy store schema.
4. If your environment includes multiple smkeydatabase instances, synchronize them. During a Policy Server upgrade, the installer tries to migrate all content in the smkeydatabase to the certificate data store.
5. Review the sections in Before You Upgrade the Policy Server.
6. Upgrade an r6.x Policy Server to 12.52.
7. Review After You Upgrade the Policy Server.
8. Upgrade an r6.x Web Agent to 12.52.
9. Upgrade the remaining r6.x Policy Servers and r6.x Web Agents to 12.52, respectively.
10. Upgrade the r6.x policy and key stores to 12.52.
11. Install the 12.52 Administrative UI.
12. (Optional) Install a Report Server.

    Note: For more information about installing the Report Server, see the Policy Server Installation Guide.

More information:

Installation and Upgrade Considerations

Download the Policy Store Schema Files

The file or files that you require to extend the policy store schema are at the root of the Policy Server installation zip.

If you are upgrading to the base release of 12.52, follow these steps:

1. Log in to the CA Support site.
2. Under Support, click Support by Product.
3. Type CA SiteMinder® in the Select a Product Page field and press Enter.
4. Under the Select a Product Page list, click Downloads.
5. Locate your specific CA SiteMinder® product in the Use the Select a Product list to locate your CA SiteMinder® product. Click the name.
6. Select a release and gen level, and click Go.
7. Save the Policy Server installation zip locally and extract the kit to a temporary location.

   The policy store schema files are included in the policy_store_schema_ext.zip.

If you are upgrading to a cumulative release (cr) of 12.52, follow these steps:

1. Log in to the CA Support site.
2. Under Support, click Support by Product.
3. Type CA SiteMinder® in the Select a Product Page field and press Enter.
4. Under the Select a Product Page list, click Recommended Reading.
5. Click CA SiteMinder® Hotfix/Cumulative Release Hot Index in the Recommend Reading list.
6. Click CA SiteMinder® Web Access Manager.
7. Click the cumulative release that you want.
8. Download the cumulative release.
9. Save the Policy Server installation zip locally and extract the kit to a temporary location.

   The policy store schema files are included in the policy_store_schema_ext.zip.

Extend the Policy Store Schema

The existing r6.x policy store schema has not changed. The 12.52 migration requires that you extend the policy store schema for policy store for objects that 12.52 requires.

If you have deployed a smkeydatabase, extend the policy store schema before upgrading your first Policy Server. Extending the schema prepares the policy store for the smkeydatabase migration to the certificate data store during a Policy Server upgrade. Extending the schema does not affect compatibility mode. The policy store continues to function as it did in r6.x.

If you have not deployed a smkeydatabase, extend the schema as part of the policy store upgrade process.

Extend the Policy Store Schema for Your Active Directory Server

Follow these steps:

1. Copy the following ZIP file to a Policy Server host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\Active Directory
   

3. Open the ActiveDirectory.ldif file and manually replace each instance of <RootDN> with the DN (domain name) that represents the policy store schema location. Do not use the policy store object location.

   Example: If the following root DN represents the policy store object:

   ou=policystore,dc=domain,dc=com
   

   Replace each instance of <RootDN> with the following DN:

   dc=domain,dc=com
   

4. Save the file.
5. Navigate to siteminder_home/bin from a command window.

   siteminder_home

   Specifies the Policy Server installation path.

6. Run the following command:

   smldapsetup ldmod -fpath/ActiveDirectory.ldif
   

   path

   Specifies the path to the schema file.

   The policy store schema is extended.

Extend Policy Store Schema for Your Active Directory LDS Server

Follow these steps:

1. Copy the following ZIP file to a Policy Server host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\Active Directory LDS
   

3. Open the ADLDS.ldif file and replace each instance of {guid} with the actual value of guid in the braces.

   Example: {CF151EA3-53A0-44A4-B4AC-DA0EBB1FF200}

4. Save the file.
5. Navigate to siteminder_home/bin from a command window.

   siteminder_home

   Specifies the Policy Server installation path

6. Run the following command:

   smldapsetup ldmod -fpath/ADLDS.ldif
   

   path

   Specifies the path to the schema file.

   The policy store schema is extended.

Extend Policy Store Schema for Your CA Directory Server

Follow these steps:

1. Copy the following ZIP file to the CA Directory host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\CA Directory
   

3. Copy the following file into the CA Directory DXHOME\config\schema directory:

   etrust.dxc
   

4. Open the CA SiteMinder® schema file (.dxg), and add the following lines to the bottom of the file:

   #CA Schema
   source "netegrity.dxc"
   source "etrust.dxc"
   

5. Edit the DXI file for the DSA by adding the following lines to the bottom of the file:
   • r12

     # cache configuration
     set max-cache-size = 100;
     set cache-attrs = all-attributes;
     set cache-load-all = true;
     set ignore-name-bindings = true;
     

     Note: The DXI file is located in DXHOME\config\servers. The max-cache-size entry is the total cache size in MB. Adjust this value according to the total memory available on the CA Directory server and overall size of the policy store.

   • r12 SP1 or later

     # cache configuration
     #set max-cache-size = 100;
     #set cache-attrs = all-attributes;
     #set cache-load-all = true;
     set ignore-name-bindings = true;
     

6. Open the default DXC file (default.dxc) for the DSA and locate the following section:

   # size limits
   set max-users = 255;
   set credits = 5;
   set max-local-ops = 100;
   set max-dsp-ops = 100;
   set max-op-size = 200;
   set multi-write-queue = 20000;
   

   Note: The default DXC file is located in DXHOME\dxserver\config\limits.

7. Edit the settings to match the following settings and save the DXC file:

   # size limits
   set max-users = 1000;
   set credits = 5;
   set max-local-ops = 1000;
   set max-dsp-ops = 1000;
   set max-op-size = 4000;
   set multi-write-queue = 20000;
   

   Note: Editing the size limits settings prevents cache size errors from appearing in your CA Directory log files.

   Important! The multi‑write‑queue setting is for text–based configurations only. If the DSA is set up with DXmanager, omit this setting.

8. Use JXplorer to access the policy store DSA.
9. Locate the root element, and then locate the following base tree structure:

   Netegrity, SiteMinder, PolicySvr4

10. Create an organizational unit (root element) under PolicySvr4 that is named:

    XPS

11. Stop and restart the DSA (as the DSA user) with the following commands:

    dxserver stop DSA_Name
    

    dxserver start DSA_Name
    

    DSA_Name

    Specifies the name of the policy store DSA.

    The policy store schema is extended.

Extend the Policy Store Schema for Your IBM DB2 Server

Follow these steps:

1. Copy the following ZIP file to the IBM DB2 host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\IBM DB2
   

3. Locate the following file:

   DB2.sql
   

4. Open a command prompt and run the following command:

   db2 -td@ [-v] -f path\DB2.sql
   

   path

   Specifies the path to the DB2 schema file.

   The policy store schema is extended.

Extend the Policy Store Schema for Your IBM Tivoli Directory Server

Follow these steps:

1. Use the IBM Tivoli Directory Server administration tool to update the policy store base tree structure. Create the following root node under ou=Netegrity,ou=SiteMinder,ou=PolicySvr4:

   ou=XPS
   

2. Copy the following ZIP file to the IBM Directory Server host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

3. Navigate to the following directory:

   schema_extension\db\IBM Tivoli Directory Server
   

4. Locate the following file:

   IBMDirectoryServer.ldif
   

5. Use the IBM Directory Server Configuration Tool to add the following file to the Manage Schema Files section of the schema configuration:

   IBMDirectoryServer.ldif
   

6. Restart the directory server.

   The policy store schema is extended.

Extend the Policy Store Schema for Your Novell eDirectory Server

Follow these steps:

1. Copy the following ZIP file to a Policy Server host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\Novell eDirectory
   

3. Locate and open the following file:

   Novell.ldif
   

4. Navigate to siteminder_home\bin from a command window.

   siteminder_home

   Specifies the Policy Server installation path.

5. Run the following command:

   ldapsearch -hhost -pport -bcontainer -ssub -DAdminDN -wAdminPW
   objectclass=ncpServer dn
   

   Example:

   ldapsearch -h192.168.1.47 -p389 -bo=nwqa47container -ssub
   -dcn=admin,o=nwqa47container -wpassword objectclass=ncpServer dn
   

   The Novell server DN opens.

6. Edit the open schema file. Replace every <ncpserver> variable with the value of the Novell server DN (domain name).

   Example: If your Novell server DN value is cn=servername,o=servercontainer, replace all instances of <ncpserver> with the following value:

   cn=servername,o=servercontainer
   

7. Save and close the schema file.
8. Run the following command:

   smldapsetup ldmod -fpath\Novell.ldif
   

   -fpath

   Specifies the path to the schema file.

   The policy store schema is extended.

Extend the Policy Store Schema for Your OpenLDAP Server

Follow these steps:

Note: This procedure assumes that the OpenLDAP server is at /usr/local/etc/openldap and that the schema files are located in the schema subdirectory.

1. Update the policy store base tree structure. Create the following root node under ou=Netegrity,ou=SiteMinder,ou=PolicySvr4:

   ou=XPS
   

2. Copy the following ZIP file to the OpenLDAP host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

3. Navigate to the following directory:

   schema_extension\db\OpenLDAP
   

4. Locate the following schema files:

   openldap_attribute_XPS.schema
   openldap_object_XPS.schema
   

5. Copy the schema files located in Step 4 to the schema folder in the OpenLDAP installation directory.
6. Type the following entry in the include section of the slapd configuration file:

   ....
   .....
   include /usr/local/etc/openldap/schema/openldap_attribute_XPS.schema
   include /usr/local/etc/openldap/schema/openldap_object_XPS.schema
   

   The policy store schema is extended.

Extend the Policy Store Schema for Your Oracle Internet Directory Server

Follow these steps:

1. Log in to the Oracle Internet Directory host system.
2. Use the Oracle catalog command line tool to index the following attribute. Indexing the attribute prevents an error from occurring when you import the default policy store objects:

   modifyTimestamp
   

   Run the following command:

   oracle_home/ldap/bin/catalog connect=conn_str add=TRUE attribute=modifyTimestamp
   

   oracle_home

   Specifies the Oracle Internet Directory installation path.

   conn_str

   Specifies the directory database connect string. If you have configured a tnsnames.ora file, then enter the net service name specified in the file.

   Note: For more information about the catalog command line tool, see the Oracle documentation.

3. Copy the following ZIP file to a Policy Server host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

4. Navigate to the following directory:

   schema_extension\db\Oracle Internet Directory
   

5. Locate the following file:

   OID_10g.ldif
   

6. Navigate to siteminder_home\bin from a command window.

   siteminder_home

   Specifies the Policy Server installation path.

7. Run the following command:

   ldapmodify -hhost -pport -dAdminDN -wAdminPW
   -c -fpath\OID_10g.ldif
   -Z -Pcert
   

   -hhost

   Specifies the IP address of the LDAP directory server.

   Example: 123.123.12.12

   -pport

   Specifies the port number of the LDAP directory server.

   Example: 3500

   -dAdminDN

   Specifies the name of the LDAP user who has the privileges to create the LDAP schema.

   -wAdminPW

   Specifies the password of the administrator that the –d option specifies.

   -c

   Specifies continuous mode (do not stop on errors).

   -fpath

   Specifies the path to the extracted schema file.

   -Z

   Specifies a connection that is encrypted by SSL.

   -Pcert

   Specifies the path of the directory where the SSL client certificate database file (cert7.db) exists.

   Example:

   If cert7.db exists in app/siteminder/ssl, specify:

   -Papp/siteminder/ssl
   

   The policy store schema is extended.

Extend the Policy Store Schema for Your Red Hat Directory Server

Follow these steps:

1. Copy the following ZIP file to a Policy Server host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\Red Hat Directory Server
   

3. Locate the following file:

   RedHat_7_1.ldif
   

4. Navigate to siteminder_home/bin from a command window.

   siteminder_home

   Specifies the Policy Server installation path.

5. Run the following command:

   smldapsetup ldmod -fpath/RedHat_7_1.ldif
   

   path

   Specifies the path to the extracted schema file.

   The policy store schema is extended.

Extend the Policy Store Schema for Your Siemens DirX Server

Follow these steps:

1. Use the DirXmanage tool to update the policy store base tree structure. Under the existing root path:

   ou=Netegrity,ou=SiteMinder,ou=PolicySvr4
   

   Create the following root node:

   ou=XPS 
   

2. Copy the ZIP file, policy_store_schema_ext.zip, to the Siemens DirX host system and extract it to a temporary location.
3. Navigate to the following directory:

   schema_extension\db\Siemens DirX
   

4. Locate the following extracted files and copy them to DirX_install_path\scripts\security\Netegrity\SiteMinder:
   • bind.tcl
   • GlobalVar.tcl
   • l-bind.cp
   • schema_ext_for_XPS.adm

   DirX_install_path

   Specifies the DirX installation path.

   Example: C:\program files\siemens\dirx

5. Locate the extracted file dirxabbr-ext.XPS and copy it to DirX_install_path\client\conf.
6. Stop and restart the DirX service.
7. Edit the GlobalVar.tcl file to update the global variables that the DirX scripts reference.

   Default values:

   • LDAP port: 389
   • Root DN: o=pqr
   • Admin username: cn=admin,o=pqr
   • Admin password: dirx

   Note: Correct the values so they apply to your existing setup.

8. Navigate to DirX_install_path\scripts\security\CA\SiteMinder.
9. Execute the following command:

   dirxadm schema_ext_for_XPS.adm
   

10. Use the DirXmanage utility to rebind to the DSA.

    Note: Watch for errors.

    The policy store schema is extended.

Extend the Policy Store Schema for Your Sun Java System Directory Server

Follow these steps:

1. Copy the following ZIP file to a Policy Server host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\Sun Java System Directory Server
   

3. Locate the following file:

   OracleDirectoryServer.ldif
   

4. Navigate to siteminder_home\bin from a command window.

   siteminder_home

   Specifies the Policy Server installation path.

5. Run the following command:

   smldapsetup ldmod -fpath\OracleDirectoryServer.ldif
   

   -fpath

   Specifies the path to the extracted schema file.

   The policy store schema is extended.

Extend the Policy Store Schema for Your Microsoft SQL Server

Follow these steps:

1. Copy the following ZIP file to the SQL Server host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\Microsoft SQL Server
   

3. Locate the following file:

   SQLServer.sql
   

4. Log in to SQL Server as the user who administers the policy store database.
5. Start the Query Analyzer.
6. Select the policy store database instance from the database list.
7. Open the file in a text editor and copy the contents of the entire file.
8. Paste the schema into the query and execute the query.

   The policy store schema is extended.

Extend the Policy Store Schema for Your MySQL Server

Follow these steps:

1. Copy the following ZIP file to the MySQL host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\MySQL
   

3. Locate the following file:

   MySQL.sql
   

4. Open the file in a text editor and copy the contents of the entire file.
5. Paste the file contents into a query.
6. Use the MySQL command line tool to execute the query.

   The policy store schema is extended.

Extend the Policy Store Schema for Your Oracle Server

Follow these steps:

1. Copy the following zip file to the Oracle host system and extract it to a temporary location:

   policy_store_schema_ext.zip
   

2. Navigate to the following directory:

   schema_extension\db\Oracle
   

3. Locate the following file:

   Oracle.sql
   

4. Log in to the Oracle server with sqlplus or another Oracle utility as the user who administers the policy store database.

   Note: We recommend that you do not create the CA SiteMinder® schema with the SYS or SYSTEM users. If necessary, create an Oracle user, such as SMOWNER, and create the schema with that user.

5. Import the file into the r6.x database instance.

   Note: If you are using sqlplus, run the schema using an @ sign.

   The policy store schema is extended.

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 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.
• 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 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.
• 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

Synchronize Key Database Instances

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

Windows

Follow these steps:

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

   installation_media

   Specifies the Policy Server installation executable.

   The Policy Server installer starts.

   Note: For a list of installation media names, see the Policy Server Release Notes.

5. 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.

1. Review the installation settings and click Install.

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

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

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

   ./installation_media
   

   installation_media

   Specifies the Policy Server installation executable.

   The Policy Server installer starts.

   Note: For a list of installation media names, see the Policy Server Release Notes.

7. 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.
8. 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.

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

UNIX Console

Follow these steps:

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

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

   ./installation_media -i console
   

   installation_media

   Specifies the Policy Server installation executable.

   The Policy Server installer starts.

   Note: For a list of installation media names, see the Policy Server Release Notes.

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

8. 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.

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

12. 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.

   The master key screen appears.

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.

Policy Server Upgrade Creates New Files

During a Policy Server upgrade, the installer creates new versions of certain files for 12.52. 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 files use the .new extension: For example, the JVMOptions.txt file from the previous version remains untouched. The installer creates an 12.52 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.

After You Upgrade the Policy Server

If your Policy Server audit log is configured to include administrator changes to policy store objects, consider the following:

• You receive a message instructing you to disable this type of administrator auditing when you open the Policy Server Management Console for the first–time.
• You receive this message because there have been changes to how this type of administrator event is included in the Policy Server audit log. You use the XPSConfig utility, not the Policy Server Management Console, to include this type of administrator event in the audit log. By default, the XPSConfig utility enables the logging of Administrator changes to policy store objects.

You continue to receive the message until you change the Administrator Changes to Policy Store Objects setting, which is located on the Logs tab, to Log No Events. The setting appears disabled after you change it, but administrator changes to policy store objects continue to be logged.

If you want to exclude this type of Administrator event from the Policy Server audit log, disable it using the XPSConfig utility.

Note: For more information about using the XPSConfig utility, see the Policy Server Administration Guide.

Upgrade an r6.x Web Agent

Upgrading Web Agents is the second step in the migration process.

CA SiteMinder® r6.x Web Agents can communicate with an 12.52 Policy Server. Therefore, you upgrade a Policy Server to 12.52 before upgrading a Web Agent to 12.52.

Before You Upgrade r6.x Web Agents

Before you upgrade Web Agents:

• (UNIX) Be sure that you upgrade the Web Agent with the same account that was used to install it. If you use a different account, the upgrade can fail.
• Back up the Web Agent Option Pack (WAOP) configuration files and uninstall the WAOP.

  Note: For more information about uninstalling the WAOP, see the Web Agent Option Pack Guide.

• Be sure that the Policy Server is configured.
• Identify the required administrator and Policy Server object names.
• Identify the Web Agent requirements.

Ensure the Policy Server is Configured

Before you upgrade the Web Agent:

• Be sure that the Policy Server can connect to the Web 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 Web 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 the Web Agent Requirements

For more information about patches and other Web Agent requirements, see the Web Agent Installation Guide.

Upgrade an r6.x Web Agent

Use the 12.52 web agent installer to upgrade an r6.x web agent. Consider the following items:

• Agents that require option pack functionality must be upgraded to 12.52 before installing the 12.52 Web Agent Option Pack.

  Note: For more information about upgrading a web agent, see the Web Agent Installation Guide. For more information about installing the 12.52 Web Agent Option Pack, see the Web Agent Option Pack Guide.

• If you have deployed Advanced Password Services, a web agent upgrade retains all LANG (translation) and CFG (configuration) files. The default 12.52 versions of the files are installed to agent_home\samples.

  agent_home

  Specifies the web agent installation path.

• If you used a startup script for r6, replace all instances of “nete_wa…” with “ca_wa…”

Custom Agent Requirements

To determine if you are required to recompile your custom agent, use the following table:

Upgrade an r6.x Policy Store

Upgrading the policy and key store is the third step in the migration process. The following sections detail how to upgrade an r6.x policy and key store to 12.52.

Options for Upgrading a Policy Store

Two paths exist for upgrading an r6.x policy store to 12.52. You can:

• Upgrade the existing policy and key store to 12.52.
• Create an 12.52 policy and key store and import the existing policy and key store data into the new instance.

This guide details the steps for upgrading an existing policy and key store.

If you want to migrate an existing policy store to a 12.52 policy and key store, follow these steps:

1. Export the policy and key store data using the r6.x version of smobjexport.

   Note: For more information, see the Policy Server Installation Guide for r6.x.

2. Create an 12.52 policy and key store.

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

3. Import the policy and key store data into the 12.52 policy and key store using the 12.52 version of smobjimport.

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

Options for Upgrading a Key Store

Two paths exist for upgrading an r6.x key store to 12.52. You can:

• Upgrade the existing policy and key store to 12.52.
• Create a stand–alone 12.52 key store and import the existing agent keys in to the new instance.

This guide details the steps for upgrading an existing policy and key store.

If you want to create a stand–alone 12.52 key store:

1. Use the r6.x version of smobjexport to export only the agent keys that are stored in the policy store.

   Note: For more information, see the r6.x Policy Server Installation Guide.

2. Create an 12.52 key store using the default policy store schema.

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

3. Use the 12.52 version of smobjimport to import the agent keys in to the 12.52 key store.

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

4. Use the Policy Server Management Console to point the Policy Server to the stand–alone key store.

   Note: For more information, see the Policy Server Management Console Help.

How to Upgrade an r6.x Policy Store

To upgrade an r6.x policy store to 12.52, complete the following procedures:

1. Stop all Policy Servers that are communicating with the policy store.
2. If you have not extended the policy store schema to facilitate a smkeydatabase migration during a Policy Server upgrade, extend the schema.
3. Import the policy store data definitions.
4. Import the default policy store objects.

   Note: If you are upgrading a legacy federation environment, there is no change to the Policy Server Option Pack (PSOP) schema.

5. If you managed your r6.x legacy federation environment using the FSS Administrative UI, run the XPS sweeper utility to complete the migration of your legacy federation objects.
6. 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:

1. Log in to the Policy Server host system.
2. 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.

3. 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:

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

   siteminder_home

   Specifies the Policy Server installation path.

2. 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.

The default policy store objects exist in the following XML files:

• smpolicy.xml
• smpolicy-secure.xml

The smpolicy-secure.xml file provides more restrictive security settings than the smpolicy.xml file. Pick only one of the previous files to import the default policy store objects.

Either file configures a new policy store and upgrades an existing store. When imported as part of an upgrade, the file does not overwrite existing default objects that were modified. These objects include the default security settings in the default Agent Configuration Object (ACO) templates.

Importing either file makes legacy federation and Web Service Variables functionality available. These features are separately licensed. If you intend to use the Web Service Variables functionality, contact your CA account representative for licensing information.

Follow these steps:

1. Open a command line window and navigate to siteminder_home\db.
2. 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
     

   –npass

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

   The policy store objects are imported.

Make the legacy federation Objects Available in the Administrative UI

If you manage your Federation Security Services (legacy federation) objects using the Policy Server UI, run the XPS sweeper utility to migrate these objects to the Administrative UI.

Follow these steps:

1. Log in to the Policy Server host system.
2. Run the following command to make your legacy federation objects available to the Administrative UI:

   XPSSweeper
   

   All legacy federation created using the Policy Server UI are available in the Administrative UI.

   You are ready to proceed to the next stage of the upgrade process, upgrading your 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:

1. Log in to the Policy Server host system.
2. 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.

3. Repeat this procedure for each Policy Server that is communicating with the policy store.

The policy store is upgraded.

Install the Administrative User Interface

Unlike previous versions of CA SiteMinder®, the Policy Server User Interface is not installed with the Policy Server. Rather, you are required to install the 12.52 Administrative UI separately.

Note: More information on installing the Administrative UI exists in the Policy Server Installation Guide.

Upgrade an r6.x Session Store

A session store upgrade is not required. The 12.52 session store schema has not changed from r6.0 SP5.

Upgrade an r6.x Audit Log Database

Using the iRecorder for CA SiteMinder®, Security Command Center (SCC) can read security-related logging data from a CA SiteMinder® SQL Server or Oracle logs database.

Note: For more information about the iRecorder for CA SiteMinder®, see the eTrust Audit iRecorder Reference Guide. For more information about importing the audit log schema, see the Policy Server Installation Guide.

The integration requires that you upgrade the schema for the audit log database by importing the sm_mssql_logs_eaudit_upgrade.sql script or sm_oracle_logs_eaudit_upgrade.sql script, which are located in policy_server_home\db\SQL. Import this script only if you are integrating CA SiteMinder® with SCC.

policy_server_home

Specifies the Policy Server installation path.

Note: The CA SiteMinder®/SCC integration does not work with DB2 logging databases.

To upgrade the audit log database, import one of the following schema scripts into an existing CA SiteMinder® audit log database:

sm_mssql_logs_eaudit_upgrade.sql

Upgrades a SQL Server audit log database from r6.x to 12.52.

sm_oracle_logs_eaudit_upgrade.sql

Upgrades an Oracle audit log database from r6.x to 12.52.

Note: If you are trying to configure or upgrade a CA SiteMinder® store listed in the CA SiteMinder® Platform Support Matrix and cannot find the procedures in this guide, see the Directory Configuration Guide.