Chapter 23 Patching OpenSSO Enterprise 8.0

Sun periodically provides update releases and patches to OpenSSO Enterprise 8.0 on http://sunsolve.sun.com/. To find the latest OpenSSO Enterprise 8.0 update release or patch, search for patch ID 141655.

An OpenSSO Enterprise 8.0 update release or patch includes a new opensso.war file that you can install using the methods described in Planning Your Patch Operation.

This chapter provides the following information about patching OpenSSO Enterprise:

• Planning Your Patch Operation

• Overview of the ssopatch Utility

• Installing the ssopatch Utility

• Patching an OpenSSO Enterprise 8.0 WAR File

• Creating a New OpenSSO Enterprise 8.0 Patched WAR File

• Running the updateschema Script

• Patching a Site With Multiple OpenSSO Enterprise Instances

Planning Your Patch Operation

This section describes the general steps to patch an OpenSSO Enterprise 8.0 release. If you are installing the opensso.war file in an update release or patch as a new deployment, see Chapter 3, Installing OpenSSO Enterprise.

To Plan Your Patch Operation

1. Check the patch and upgrade paths in Table 23–1.

2. If you are not familiar with ssopatch, read the Overview of the ssopatch Utility.

3. Before you install an OpenSSO Enterprise 8.0 update release or patch, check the information about the new features, hardware and software requirements, and issues and workarounds in the following documents:

   • Sun OpenSSO Enterprise 8.0 Release Notes

   • Sun OpenSSO Enterprise 8.0 Update 1 Release Notes

4. Download the lastest OpenSSO Enterprise update release or patch (patch ID 141655) from http://sunsolve.sun.com/.

5. Check the README file associated with the patch for information such as the issues fixed in the patch.

6. Install ssopatch for your platform, as described in Installing the ssopatch Utility.

7. Determine if your existing WAR file has been customized or modified, by comparing your WAR file to its internal manifest file.

8. Compare your existing WAR file and the update release WAR file, to return the files customized in the original WAR, files updated in the new WAR file, and files added or deleted between the two WAR versions.

9. Backup your existing OpenSSO WAR file and configuration data.

10. Patch your OpenSSO Enterprise WAR file, as described in Patching an OpenSSO Enterprise 8.0 WAR File.

11. Run the updateschema script, as described in Running the updateschema Script.

OpenSSO Patch and Upgrade Paths

Overview of the ssopatch Utility

The ssopatch utility is a Java command-line utility that is available on Solaris and Linux systems as ssopatch and on Windows systems as ssopatch.bat.

The syntax for ssopatch in OpenSSO Enterprise 8.0 update releases has changed considerably since the OpenSSO Enterprise 8.0 release. For the new syntax, see Running the ssopatch Utility in this section.

The ssopatch patch utility can perform these functions:

• Compares an OpenSSO Enterprise WAR to its original manifest, to determine if the WAR file has been customized or modified

• Compare two OpenSSO Enterprise WAR files, to determine the differences between the two files including any customizations made to the original WAR file and any changes in the new WAR file

• Generates a staging area of the files required to generate a new patched OpenSSO Enterprise WAR file

The ssopatch utility uses a manifest file to determine the contents of a specific OpenSSO Enterprise WAR file. A manifest file is an ASCII text file that contains:

• A string that identifies the specific version of the OpenSSO Enterprise WAR file

• All of the individual files in the OpenSSO Enterprise WAR file, with checksum information for each file

The manifest file is usually named OpenSSO.manifest and is stored in the in the META-INF directory of the OpenSSO Enterprise WAR file. The ssopatch utility sends its results to the standard output (stdout). If you prefer, you can capture the ssopatch output by redirecting the output to a file. If ssopatch finishes successfully, it returns a zero (0) exit code. If errors occur, ssopatch returns a non-zero exit code.

Running the ssopatch Utility

To run the ssopatch utility, follow this usage:

ssopatch --help|-? [--locale|-l]

ssopatch --war-file|-o [--manifest|-m] [--locale|-l]

ssopatch --war-file|-o 
--war-file-compare|-c 
[--staging|-s] 
[--locale|-l] 
[--override|-r] 
[--overwrite|-w]

where the options are:

Installing the ssopatch Utility

Before you install the ssopatch utility:

• Download and unzip the patch ZIP file in the latest OpenSSO Enterprise 8.0 update or patch release (patch ID 141655).

• Set your JAVA_HOME environment variable point to JDK 1.5 or later.

Always install the latest version of the ssopatch or ssopatch.bat utility (and the corresponding updateschema.sh or updateschema.bat script) from the OpenSSO Enterprise 8.0 patch release you are installing.

To Install the ssopatch Utility

1. Locate the ssoPatchTools.zip file in the zip-root/opensso/tools directory, where zip-root is where you unzipped the update release patch ZIP file.

2. Create a new directory to unzip the ssoPatchTools.zip file. For example: ssopatch-files

3. Unzip the ssoPatchTools.zip file in the new directory. You then get these files:

   • README

   • ssopatch and ssopatch.bat utilities

   • resources directory, which contains the ssopatch properties files

   • lib directory, which contains the ssopatch JAR files

   • patch directory, which contains the updateschema and updateschema.bat scripts and related XML files

4. If you want to run the ssopatch utility from a directory other than its current directory without providing the full path, add the utility to your PATH variable.

Patching an OpenSSO Enterprise 8.0 WAR File

The patching operation compares the manifests for each WAR file and then shows:

• Files customized in the original OpenSSO Enterprise 8.0 WAR file

• Files updated in a new OpenSSO Enterprise 8.0 update release WAR file

• Files added or removed between the two WAR file versions

The ssopatch utility then copies the appropriate files to a staging directory, where you must add any customizations before you create and deploy the new patched WAR file.

To Patch OpenSSO Enterprise 8.0

Before You Begin

Although ssopatch does not modify your original opensso.war file, it is recommended that you back up this file, in case you need to back out the patched opensso.war file. Backup your existing OpenSSO Enterprise WAR file and configuration data:

• Copy your existing OpenSSO Enterprise WAR file to a safe location. Then, if you need to back out an update for some reason, you can re-deploy the backup copy of your WAR file.

• Backup your configuration data, as described in the Sun OpenSSO Enterprise 8.0 Administration Guide.

1. Make sure that your JAVA_HOME environment variable points to JDK 1.5 or later.

2. Although ssopatch does not modify your original opensso.war file, it is recommended that you back up this file, in case you need to back out the patched opensso.war file.

3. Run ssopatch to create the staging area. For example:

   ./ssopatch -o /zip-root/opensso/deployable-war/opensso.war 
   -c /u1/opensso/deployable-war/opensso.war --override -s /tmp/staging
   
   Generating Manifest for: /zip-root/opensso/deployable-war/opensso.war
   Original manifest: Enterprise 8.0 Build 6(200810311055)
   New manifest: Enterprise 8.0 Update 1 Build 6.1(200904300525)
   Versions are compatible
   Generating Manifest for: /u1/opensso/deployable-war/opensso.war
   Comparing manifest of /zip-root/opensso/deployable-war/opensso.war (generated-200905051031) 
     against /u1/opensso/deployable-war/opensso.war (generated-200905051032)
   File was customized in original, but not found in new war. 
   Staging area using original war version (samples/saml2/sae/header.jsp)
   File was customized in original, but not found in new war. 
   Staging area using original war version (WEB-INF/template/opends/config/upgrade/config.ldif.4517)
   File was customized in original, but not found in new war. 
   Staging area using original war version (WEB-INF/template/opends/config/upgrade/schema.ldif.4517)
   Differences: 1813
   Customizations: 0

   In this example, /tmp/staging is the staging area where ssopatch copies the files.

4. Update the files as needed in the staging area, using the results of the previous step.

   The following table shows the potential results of the patch operation and the actions you might need to take.

   ssopatch Results	Explanation and Action Required
   File not in original war (filename)	The indicated file does not exist in the original OpenSSO WAR but is in the latest version of the OpenSSO WAR.  Action: None
   File updated in new war (filename)	The indicated file exists in both the original and new OpenSSO WAR files and has been updated in the latest version of the OpenSSO WAR. No customizations have been done in the original OpenSSO WAR.  Action: None
   File customized (filename)	The indicated file exists in both OpenSSO WAR files, has been customized in the original version of the WAR, but has not been updated in the latest version of the WAR.  Action: None
   May require manual customization (filename)	The file exists in both OpenSSO WAR files, has been customized in the original version of the WAR, and has been updated in the latest version of the WAR.  Action: if you want your customizations in the file, you must manually add them to the new updated file in the staging directory.
   File was customized in original, but not found in new war	The file existed in the original WAR file, but is not in the new WAR.  Action: None.

Creating a New OpenSSO Enterprise 8.0 Patched WAR File

To Create a New OpenSSO Enterprise 8.0 Patched WAR File

1. Create a new OpenSSO Enterprise WAR file from the files in the staging area. For example:

   cd /tmp/staging
   jar cvf /patched/opensso.war *

   where /patched/opensso.war is the patched OpenSSO Enterprise WAR 8.0 file.

2. Redeploy the /patched/opensso.war file to the web container using the original deploy URI. For example: /opensso

Running the updateschema Script

After you run ssopatch, run the updateschema.sh on Solaris or Linux systems or updateschema.bat on Windows. The script updates the OpenSSO Enterprise server version, adds new default server properties, adds new attribute schemas required for fixes and enhancements in the OpenSSO Enterprise 8.0 update release. You must run updateschema in order to update the server version.

To Run the updateschema Script

Before You Begin

• The updateschema.sh or updateschema.bat script requires the OpenSSO Enterprise 8.0 Update 1 or later version of the ssoadm command-line utility. Therefore, before you run this script, install the latest admin tools from the OpenSSO Enterprise 8.0 update release tools, as described in Installing the OpenSSO Enterprise Utilities and Scripts in the ssoAdminTools.zip File.

• Also, always run the latest version of the updateschema.sh or updateschema.bat script from the patch release you are installing.

1. Change to the patch-tools/patch directory, where patch-tools is where you unzipped ssoPatchTools.zip.

2. Run updateschema.sh or updateschema.bat.

3. When the scripts prompts you, provide the following information:

   • Full path to the ssoadm utility (excluding ssoadm itself). For example: /opt/ssotools/opensso/bin

   • amadmin password

   The updateschema.sh or updateschema.bat script writes any messages or errors to the standard output.

Next Steps

OpenSSO Enterprise 8.0 Update Release Configuration Changes. The patched OpenSSO Enterprise 8.0 WAR file might have configuration changes that were not in your original WAR file. Any configuration changes, if any, will be documented separately for the patch. Check the patch documentation and the Release Notes for more information about any configuration changes. (The version string in the OpenSSO manifest file will change, even if there are no configuration changes in the new WAR file.)

Patching a Site With Multiple OpenSSO Enterprise Instances

In this scenario, you have configured OpenSSO Enterprise as a site with multiple server instances and you want to patch each server instance.

To Patch a Site With Multiple OpenSSO Enterprise Instances

1. Patch the OpenSSO Enterprise WAR file on each OpenSSO Enterprise server instance, as described in Patching an OpenSSO Enterprise 8.0 WAR File.

2. On the first OpenSSO Enterprise instance only, run the updateschema or updateschema.bat script, as described in Running the updateschema Script.

3. Restart the web container for each OpenSSO Enterprise server instance.