{section}
{column:width=75%}
{anchor:topofpage}
*Sun OpenSSO Enterprise 8.0 Update 1* is available as patch *141655-01* on [http://sunsolve.sun.com/].
Before you install Sun OpenSSO Enterprise 8.0 Update 1, check the information about new features, hardware and software requirements, and issues and workarounds in the [Release Notes|http://wikis.sun.com/x/SAP7BQ].
OpenSSO Enterprise 8.0 Update 1 includes an {{opensso.war}} file that you can install using these methods:
* *Patch an existing OpenSSO Enterprise 8.0 deployment*: Use the {{ssopatch}} utility in Update 1 to patch an existing OpenSSO Enterprise 8.0 deployment, as described in this article.
*Note* -- Sun supports patching only OpenSSO Enterprise 8.0 releases. For example, patching OpenSSO Enterprise 8.0 with OpenSSO Enterprise 8.0 Update 1 is supported. Patching an OpenSSO Express or a nightly build with Update 1, however, is not supported.
* *Install a new OpenSSO Enterprise 8.0 Update 1 deployment:* Install and configure the OpenSSO Enterprise 8.0 Update 1 {{opensso.war}} file, as
described in the [Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide|http://docs.sun.com/doc/820-3320].
* *Create a new specialized WAR file*: Use the {{createwar}} script to create one of the following new WAR files from the Update 1 {{opensso.war}} file:
** OpenSSO Administration console only WAR
** Distributed Authentication UI server WAR
** OpenSSO server only WAR, without the Administration Console
** IDP Discovery Service WAR
For information, see [Creating a Specialized OpenSSO Enterprise 8.0 Update 1 WAR File|http://wikis.sun.com/x/JoYrBg].
* *Patch an existing specialized OpenSSO Enterprise WAR file*: Use the {{ssopatch}} utility in Update 1 to patch an existing specialized OpenSSO Enterprise 8.0 WAR file, as described in [Patching a Specialized OpenSSO Enterprise WAR|#PatchSpecializedWAR]
----
*Note* -- If you are running Access Manager 7.1 or Access Manager 7 2005Q4 and you want to upgrade to Update 1, follow these steps:
# Upgrade Access Manager 7.x to OpenSSO Enterprise 8.0, as described in the [OpenSSO Enterprise 8.0 Upgrade Guide|http://docs.sun.com/doc/820-5019/6ngeodr62?a=view].
# Apply the Update 1 patch, as described in this article.
----
h1. OpenSSO Enterprise 8.0 Update 1 Patches
Sun periodically releases patches for OpenSSO Enterprise 8.0 Update 1. For information about these patches, see the [OpenSSO Enterprise 8.0 Update 1 Release Notes|http://wikis.sun.com/x/SAP7BQ].
h1. Planning Your Patch Operation
h4. To Patch OpenSSO Enterprise 8.0:
# Read the [Overview of the ssopatch Utility|#ghouj].
# Install the patch utility for your platform, as described in [Installing the {{ssopatch}} Utility|#ghomt].
# Get information about your existing WAR file, to determine if your existing WAR file has been customized or modified, as described in [Comparing an OpenSSO Enterprise WAR File to Its Internal Manifest|#ghool].
# Compare your existing WAR file and the Update 1 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, as described in [Comparing Two OpenSSO Enterprise WAR Files|#ghole].
# Backup and archive your existing Opensso WAR file, as described in [Backing Up an OpenSSO Enterprise WAR File|#buaoewf].
# Patch your OpenSSO Enterprise WAR File, as described in [Patching an OpenSSO Enterprise WAR File|#ghona].
# Run the {{updateschema}} script, as described in [Running the {{updateschema}} Script|#rtouss].
*Note* -- If you are patching a specialized WAR file that you generated from an {{opensso.war}}, such as an OpenSSO server only, administration console only, Distributed Authentication UI server, or IDP Discovery Service WAR, see [Patching a Specialized OpenSSO Enterprise WAR|#pasoewf].
{anchor:ghouj}
h1. 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 as {{ssopatch.bat}}.
*Note* -- The syntax for {{ssopatch}} in OpenSSO Enterprise 8.0 Update 1 has changed considerably since the OpenSSO Enterprise 8.0 release. For the new syntax, see [Running the {{ssopatch}} Utility|#ghork].
The {{ssopatch}} patch utility performs 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
* Creates a manifest file that you can include in a customized OpenSSO Enterprise WAR (such as a console only WAR or distributed authentication UI server WAR).
After you download and unzip the OpenSSO Enterprise 8.0 Update 1 ZIP file ({{opensso_enterprise_80U1.zip}}), the patch utilities and related files are available in the {{ssoPatchTools.zip}} file, in the {{{_}zip-root_/opensso/tools}} directory, where _zip-root_ is where you unzipped {{opensso_enterprise_80U1.zip}}.
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.
{anchor:ghpji}
{anchor:ghomt}
h1. Installing the {{ssopatch}} Utility
Before you install the {{ssopatch}} utility, you must download and unzip the OpenSSO Enterprise 8.0 Update 1 ZIP file ({{opensso_enterprise_80U1.zip}}).
{anchor:ghonq}
h3. To Install the {{ssopatch}} Utility
# Locate the {{ssoPatchTools.zip}} file in the {{{_}zip-root_/opensso/tools}} directory, where {{zip-root}} is where you unzipped {{opensso_enterprise_80U1.zip}}.
# Create a new directory to unzip the {{ssoPatchTools.zip}} file. For example: {{ssopatchtools}}
# Unzip the {{ssoPatchTools.zip}} file in the new directory.
*Note* -- 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.
The following table describes the files in {{ssoPatchTools.zip}}.
|| File or Directory \\ || Description \\ ||
| {{README.patch}} | Readme that describes {{ssopatch}} |
| {{/lib}} | Required {{ssopatch}} JAR files |
| {{/patch}} | {{updateschema}} and {{updateschema.bat}} scripts and related XML files |
| {{/resources}} | Required properties files |
| {{ssopatch}} and {{ssopatch.bat}} | Utilities for Solaris, Linux, and Windows systems |
{anchor:buaoewf}
h1. Backing Up an OpenSSO Enterprise WAR File
Before you begin, 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 Update 1 for some reason, you can re-deploy your backup copy of the WAR file.
* Backup your configuration data, as described in [Backing Up and Restoring OpenSSO Enterprise Server Configuration|http://docs.sun.com/doc/820-3885/backup].
{anchor:ghork}
h1. Running the {{ssopatch}} Utility
h3. To run the {{ssopatch}} utility, follow this usage:
{noformat}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]
{noformat}
where the options are:
* {{\--war-file\|-o}} specifies a path to a WAR file (such as {{opensso.war}}) that has previously been deployed.
* {{\--manifest\|-m}} specifies the path to the manifest file you want to create. The manifest file will be generated from the WAR file indicated by {{\--war-file\|-o}} if this option is provided.
* {{\--war-file-compare\|-c}} species a path to a WAR file to compare against against the WAR file indicated by {{\--war-file\|-o}}.
* {{\--staging\|-s}} specifies a path to the staging area where the files from an OpenSSO Enterprise WAR will be written.
* {{\--locale\|-l}} specifies the locale to be used. If this option is not specified, {{ssopatch}} uses the default system locale.
* {{\--override\|-r}} overrides revision checking for the two WAR files. Revision checking determines the versions of the WAR files and continues only if the versions are compatible. This option allows you to override this check.
Default is false (revision checking is performed).
* {{\--overwrite\|-w}} overwrites the files in the existing staging area. Default is false (files are not overwritten).
{anchor:ghool}
h1. Comparing an OpenSSO Enterprise WAR File to Its Internal Manifest
Use this procedure to determine if an OpenSSO Enterprise WAR file has been customized or modified since it was downloaded.
The {{ssopatch}} utility generates a new internal manifest file and then compares this internal manifest against the manifest stored inside the original OpenSSO Enterprise WAR file in the {{META-INF}} directory.
h3. To Compare an OpenSSO Enterprise WAR File to Its Internal Manifest
# Make sure that your {{JAVA_HOME}} environment variable points to JDK 1.5 or later and that the {{ssopatch}} utility is specified in your {{PATH}} variable.
# Run {{ssopatch}} to compare the OpenSSO Enterprise WAR file to its internal manifest. For example:
{noformat}
./ssopatch -o /zip-root/opensso/deployable-war/opensso.war
Generating Manifest for: /zip-root/opensso/deployable-war/opensso.war
Comparing manifest of Internal (Enterprise 8.0 Build 6(200810311055))
against /zip-root/opensso/deployable-war/opensso.war (generated-200905050855)
File not in original war (images/login-origimage.jpg)
File updated in new war (images/login-backimage.jpg)
File updated in new war (WEB-INF/classes/amConfigurator.properties)
Differences: 3
{noformat}
This example shows these changes to the original WAR file:
* {{images/login-origimage.jpg}} is in {{opensso.war}} but was not found in the original manifest.
* {{images/login-backimage.jpg}} has been customized in {{opensso.war}} from the original manifest.
* {{WEB-INF/classes/amConfigurator.properties}} file has been customized in {{opensso.war}} from the original manifest.
{anchor:ghole}
h1. Comparing Two OpenSSO Enterprise WAR Files
Use this procedure to compare two WAR files, to show the files that have been:
* Customized in an original OpenSSO Enterprise WAR
* Updated in a new OpenSSO Enterprise WAR file
* Added or deleted between the two OpenSSO Enterprise WAR versions
{anchor:ghovd}
h3. To Compare Two OpenSSO Enterprise WAR Files
# Make sure that your {{JAVA_HOME}} environment variable points to JDK 1.5 or later and that the {{ssopatch}} utility is specified in your {{PATH}} variable.
# Run {{ssopatch}} to compare the two WAR files. In the example, the {{\--override}} option is used to override the revision checking between the two WAR files:
{noformat}
./ssopatch -o /zip-root/opensso/deployable-war/opensso.war
-c /u1/opensso/deployable-war/opensso.war --override
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-200905050919) against
/u1/opensso/deployable-war/opensso.war (generated-200905050920)
File updated in new war(WEB-INF/classes/amClientDetection_en.properties)
File updated in new war(WEB-INF/classes/fmSAMLConfiguration_fr.properties)
...
Differences: 1821
Customizations: 3
{noformat}
This example shows the files that have been updated and customized in the new WAR file.
{anchor:ghona}
h1. Patching an OpenSSO Enterprise WAR File
Use this procedure to create a new staging area, where an original WAR file is merged with a new WAR file.
This operation compares the manifests for each WAR file and then shows:
* Files customized in the original WAR file
* Files updated in a new WAR file
* Files added or removed between the two WAR file versions
The {{ssopatch}} then copies the appropriate files to a staging directory, where you must add any customizations before you create and deploy the new patched WAR.
{anchor:ghotn}
h3. To Create a Staging Area to Patch an OpenSSO Enterprise WAR File
# Make sure that your {{JAVA_HOME}} environment variable points to JDK 1.5 or later and that the {{ssopatch}} utility is specified in your {{PATH}} variable.
# Although the {{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.
# Run {{ssopatch}} to create the staging area. For example:
{noformat}
./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
{noformat}
In this example, {{/tmp/staging}} is the staging area where {{ssopatch}} copies the files.
Update the files as needed in the staging-area, using the results of the previous step.
Use the following table to determine the action you might need to take for each file before you generate a new patched WAR file.
|| {{ssopatch}} Results || Explanation and Action Required ||
| {{File not in original war (_filename_)}} | The indicated file does not exist in the original WAR file but is in the latest version of the WAR file. \\
*Action*: None |
| {{File updated in new war (_filename_)}} | The indicated file exists in both the original and new WAR files and has been updated in the latest version of the WAR file. No customizations have been done in the original WAR file. \\
*Action*: None |
| {{File customized (_filename_)}} | The indicated file exists in both WAR files, has been customized in the original version of the WAR file, but has not been updated in the latest version of the WAR file. \\
*Action*: None |
| {{May require manual customization (_filename_)}} | The file exists in both WAR files, has been customized in the original version of the WAR file, and has been updated in the latest version of the WAR file. \\
*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. |
*Next Steps*
# Create a new OpenSSO Enterprise WAR file from the files in the staging area. For example:
{noformat}cd /tmp/staging
jar cvf /patched/opensso.war *
{noformat}where {{/patched/opensso.war}} is the name of the new patched OpenSSO Enterprise WAR file.
# Redeploy the {{/patched/opensso.war}} file to the web container using the original deploy URI. For example, {{/opensso}}
*OpenSSO configuration changes*. A new OpenSSO Enterprise WAR file might have configuration changes that were not in your original WAR file. Any configuration changes, if any, will be documented separately for each patch. Check the patch documentation and the [Release Notes|http://docs.sun.com/doc/820-3745] 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.)
If you need to back out your patched version, undeploy the patched WAR file and then redeploy your original WAR file.
{anchor:ghonx}
h1. Creating an OpenSSO Enterprise WAR Manifest File
An OpenSSO manifest file is a text file that identifies all of the individual files in a WAR file for a specific release, with checksum information for each file.
Use this procedure to create a manifest file that you can include in a specialized OpenSSO Enterprise WAR, such as an OpenSSO Enterprise server only, administration console only, Distributed Authentication UI server, or IDP Discovery Service WAR
{anchor:ghold}
h3. To Create an OpenSSO Enterprise WAR Manifest File
# Make sure that your {{JAVA_HOME}} environment variable points to JDK 1.5 or later and that the {{ssopatch}} utility is specified in your {{PATH}} variable.
# Run {{ssopatch}} to create the OpenSSO manifest file. For example:
{noformat}
./ssopatch -o zip-root/opensso/deployable-war/opensso.war --manifest /tmp/manifest
{noformat}
where {{opensso.war}} is an existing OpenSSO Enterprise WAR file.
The {{ssopatch}} utility creates a new manifest file named {{manifest}} in the the {{/tmp}} directory.
# To allow the WAR file to be patched, copy this new manifest file to the {{META-INF}} directory inside the {{opensso.war}} file. For example:
{noformat}mkdir META-INF
cp /tmp/manifest META-INF
jar uf opensso.war META-INF/manifest
{noformat}
{anchor:pasoewf}
h1. Patching a Specialized OpenSSO Enterprise WAR
If you have previously created a specialized OpenSSO Enterprise WAR, such as an OpenSSO Enterprise server only, administration console only, Distributed Authentication UI server, or IDP Discovery Service WAR, you can patch it by using the {{ssopatch}} utility.
h3. To Patch a Specialized OpenSSO Enterprise WAR
# Create a manifest file for your specialized OpenSSO Enterprise WAR, as described in [Creating an OpenSSO Enterprise WAR Manifest File|#ghonx].
*Note*: Create the manifest file based on the original OpenSSO Enterprise 8.0 {{opensso.war}}, as delivered from Sun, prior to any customizations you might have done. If the manifest is created after customizations, {{ssopatch}} might use the files from Update 1, rather than your customizations, so you would need to re-do your customizations after patching.
# Generate the specialized OpenSSO Enterprise WAR from the OpenSSO Enterprise 8.0 Update 1 ((opensso.war)) file, as described in [Creating a Specialized OpenSSO Enterprise 8.0 Update 1 WAR File|http://wikis.sun.com/x/JoYrBg].
# Use the {{ssopatch}} utility to compare the your old and new WAR files.
# Generate a staging area for the new specialized WAR file, as described in [Creating a Staging Area to Patch an OpenSSO Enterprise WAR File|#ghona].
{anchor:rtouss}
h1. 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 bug fixes and enhancements in Update 1. You must run {{updateschema}} in order to update the server version.
h4. Before You Begin
The {{updateschema.sh}} or {{updateschema.bat}} script requires the Update 1 version of the {{ssoadm}} command-line utility. Therefore, before you run this script, install the Update 1 admin tools, as described in [Installing the OpenSSO Enterprise 8.0 Update 1 Admin Tools|http://wikis.sun.com/x/tYF1BQ].
h4. To Run the {{updateschema}} Script
# Change to the {{{_}patch-tools_/patch}} directory, where {{{_}patch-tools{_}}} is where you unzipped {{ssoPatchTools.zip}}.
# Run {{updateschema.sh}} or {{updateschema.bat}}. For example, on Solaris systems:
{{./updateschema.sh}}
# 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.
h1. Backing Out a Patch Installation
If you need to back out your patch installation, simply redeploy the original {{opensso.war}} file (or specialized WAR file).
[Top of Page|#topofpage]
{column}
{column:width=25%}
{panel:title=Contents|titleBGColor=white|bgColor=white}
{toc:maxLevel=1}
{panel}
{column}
{section}
{column:width=75%}
{anchor:topofpage}
*Sun OpenSSO Enterprise 8.0 Update 1* is available as patch *141655-01* on [http://sunsolve.sun.com/].
Before you install Sun OpenSSO Enterprise 8.0 Update 1, check the information about new features, hardware and software requirements, and issues and workarounds in the [Release Notes|http://wikis.sun.com/x/SAP7BQ].
OpenSSO Enterprise 8.0 Update 1 includes an {{opensso.war}} file that you can install using these methods:
* *Patch an existing OpenSSO Enterprise 8.0 deployment*: Use the {{ssopatch}} utility in Update 1 to patch an existing OpenSSO Enterprise 8.0 deployment, as described in this article.
*Note* -- Sun supports patching only OpenSSO Enterprise 8.0 releases. For example, patching OpenSSO Enterprise 8.0 with OpenSSO Enterprise 8.0 Update 1 is supported. Patching an OpenSSO Express or a nightly build with Update 1, however, is not supported.
* *Install a new OpenSSO Enterprise 8.0 Update 1 deployment:* Install and configure the OpenSSO Enterprise 8.0 Update 1 {{opensso.war}} file, as
described in the [Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide|http://docs.sun.com/doc/820-3320].
* *Create a new specialized WAR file*: Use the {{createwar}} script to create one of the following new WAR files from the Update 1 {{opensso.war}} file:
** OpenSSO Administration console only WAR
** Distributed Authentication UI server WAR
** OpenSSO server only WAR, without the Administration Console
** IDP Discovery Service WAR
For information, see [Creating a Specialized OpenSSO Enterprise 8.0 Update 1 WAR File|http://wikis.sun.com/x/JoYrBg].
* *Patch an existing specialized OpenSSO Enterprise WAR file*: Use the {{ssopatch}} utility in Update 1 to patch an existing specialized OpenSSO Enterprise 8.0 WAR file, as described in [Patching a Specialized OpenSSO Enterprise WAR|#PatchSpecializedWAR]
----
*Note* -- If you are running Access Manager 7.1 or Access Manager 7 2005Q4 and you want to upgrade to Update 1, follow these steps:
# Upgrade Access Manager 7.x to OpenSSO Enterprise 8.0, as described in the [OpenSSO Enterprise 8.0 Upgrade Guide|http://docs.sun.com/doc/820-5019/6ngeodr62?a=view].
# Apply the Update 1 patch, as described in this article.
----
h1. OpenSSO Enterprise 8.0 Update 1 Patches
Sun periodically releases patches for OpenSSO Enterprise 8.0 Update 1. For information about these patches, see the [OpenSSO Enterprise 8.0 Update 1 Release Notes|http://wikis.sun.com/x/SAP7BQ].
h1. Planning Your Patch Operation
h4. To Patch OpenSSO Enterprise 8.0:
# Read the [Overview of the ssopatch Utility|#ghouj].
# Install the patch utility for your platform, as described in [Installing the {{ssopatch}} Utility|#ghomt].
# Get information about your existing WAR file, to determine if your existing WAR file has been customized or modified, as described in [Comparing an OpenSSO Enterprise WAR File to Its Internal Manifest|#ghool].
# Compare your existing WAR file and the Update 1 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, as described in [Comparing Two OpenSSO Enterprise WAR Files|#ghole].
# Backup and archive your existing Opensso WAR file, as described in [Backing Up an OpenSSO Enterprise WAR File|#buaoewf].
# Patch your OpenSSO Enterprise WAR File, as described in [Patching an OpenSSO Enterprise WAR File|#ghona].
# Run the {{updateschema}} script, as described in [Running the {{updateschema}} Script|#rtouss].
*Note* -- If you are patching a specialized WAR file that you generated from an {{opensso.war}}, such as an OpenSSO server only, administration console only, Distributed Authentication UI server, or IDP Discovery Service WAR, see [Patching a Specialized OpenSSO Enterprise WAR|#pasoewf].
{anchor:ghouj}
h1. 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 as {{ssopatch.bat}}.
*Note* -- The syntax for {{ssopatch}} in OpenSSO Enterprise 8.0 Update 1 has changed considerably since the OpenSSO Enterprise 8.0 release. For the new syntax, see [Running the {{ssopatch}} Utility|#ghork].
The {{ssopatch}} patch utility performs 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
* Creates a manifest file that you can include in a customized OpenSSO Enterprise WAR (such as a console only WAR or distributed authentication UI server WAR).
After you download and unzip the OpenSSO Enterprise 8.0 Update 1 ZIP file ({{opensso_enterprise_80U1.zip}}), the patch utilities and related files are available in the {{ssoPatchTools.zip}} file, in the {{{_}zip-root_/opensso/tools}} directory, where _zip-root_ is where you unzipped {{opensso_enterprise_80U1.zip}}.
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.
{anchor:ghpji}
{anchor:ghomt}
h1. Installing the {{ssopatch}} Utility
Before you install the {{ssopatch}} utility, you must download and unzip the OpenSSO Enterprise 8.0 Update 1 ZIP file ({{opensso_enterprise_80U1.zip}}).
{anchor:ghonq}
h3. To Install the {{ssopatch}} Utility
# Locate the {{ssoPatchTools.zip}} file in the {{{_}zip-root_/opensso/tools}} directory, where {{zip-root}} is where you unzipped {{opensso_enterprise_80U1.zip}}.
# Create a new directory to unzip the {{ssoPatchTools.zip}} file. For example: {{ssopatchtools}}
# Unzip the {{ssoPatchTools.zip}} file in the new directory.
*Note* -- 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.
The following table describes the files in {{ssoPatchTools.zip}}.
|| File or Directory \\ || Description \\ ||
| {{README.patch}} | Readme that describes {{ssopatch}} |
| {{/lib}} | Required {{ssopatch}} JAR files |
| {{/patch}} | {{updateschema}} and {{updateschema.bat}} scripts and related XML files |
| {{/resources}} | Required properties files |
| {{ssopatch}} and {{ssopatch.bat}} | Utilities for Solaris, Linux, and Windows systems |
{anchor:buaoewf}
h1. Backing Up an OpenSSO Enterprise WAR File
Before you begin, 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 Update 1 for some reason, you can re-deploy your backup copy of the WAR file.
* Backup your configuration data, as described in [Backing Up and Restoring OpenSSO Enterprise Server Configuration|http://docs.sun.com/doc/820-3885/backup].
{anchor:ghork}
h1. Running the {{ssopatch}} Utility
h3. To run the {{ssopatch}} utility, follow this usage:
{noformat}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]
{noformat}
where the options are:
* {{\--war-file\|-o}} specifies a path to a WAR file (such as {{opensso.war}}) that has previously been deployed.
* {{\--manifest\|-m}} specifies the path to the manifest file you want to create. The manifest file will be generated from the WAR file indicated by {{\--war-file\|-o}} if this option is provided.
* {{\--war-file-compare\|-c}} species a path to a WAR file to compare against against the WAR file indicated by {{\--war-file\|-o}}.
* {{\--staging\|-s}} specifies a path to the staging area where the files from an OpenSSO Enterprise WAR will be written.
* {{\--locale\|-l}} specifies the locale to be used. If this option is not specified, {{ssopatch}} uses the default system locale.
* {{\--override\|-r}} overrides revision checking for the two WAR files. Revision checking determines the versions of the WAR files and continues only if the versions are compatible. This option allows you to override this check.
Default is false (revision checking is performed).
* {{\--overwrite\|-w}} overwrites the files in the existing staging area. Default is false (files are not overwritten).
{anchor:ghool}
h1. Comparing an OpenSSO Enterprise WAR File to Its Internal Manifest
Use this procedure to determine if an OpenSSO Enterprise WAR file has been customized or modified since it was downloaded.
The {{ssopatch}} utility generates a new internal manifest file and then compares this internal manifest against the manifest stored inside the original OpenSSO Enterprise WAR file in the {{META-INF}} directory.
h3. To Compare an OpenSSO Enterprise WAR File to Its Internal Manifest
# Make sure that your {{JAVA_HOME}} environment variable points to JDK 1.5 or later and that the {{ssopatch}} utility is specified in your {{PATH}} variable.
# Run {{ssopatch}} to compare the OpenSSO Enterprise WAR file to its internal manifest. For example:
{noformat}
./ssopatch -o /zip-root/opensso/deployable-war/opensso.war
Generating Manifest for: /zip-root/opensso/deployable-war/opensso.war
Comparing manifest of Internal (Enterprise 8.0 Build 6(200810311055))
against /zip-root/opensso/deployable-war/opensso.war (generated-200905050855)
File not in original war (images/login-origimage.jpg)
File updated in new war (images/login-backimage.jpg)
File updated in new war (WEB-INF/classes/amConfigurator.properties)
Differences: 3
{noformat}
This example shows these changes to the original WAR file:
* {{images/login-origimage.jpg}} is in {{opensso.war}} but was not found in the original manifest.
* {{images/login-backimage.jpg}} has been customized in {{opensso.war}} from the original manifest.
* {{WEB-INF/classes/amConfigurator.properties}} file has been customized in {{opensso.war}} from the original manifest.
{anchor:ghole}
h1. Comparing Two OpenSSO Enterprise WAR Files
Use this procedure to compare two WAR files, to show the files that have been:
* Customized in an original OpenSSO Enterprise WAR
* Updated in a new OpenSSO Enterprise WAR file
* Added or deleted between the two OpenSSO Enterprise WAR versions
{anchor:ghovd}
h3. To Compare Two OpenSSO Enterprise WAR Files
# Make sure that your {{JAVA_HOME}} environment variable points to JDK 1.5 or later and that the {{ssopatch}} utility is specified in your {{PATH}} variable.
# Run {{ssopatch}} to compare the two WAR files. In the example, the {{\--override}} option is used to override the revision checking between the two WAR files:
{noformat}
./ssopatch -o /zip-root/opensso/deployable-war/opensso.war
-c /u1/opensso/deployable-war/opensso.war --override
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-200905050919) against
/u1/opensso/deployable-war/opensso.war (generated-200905050920)
File updated in new war(WEB-INF/classes/amClientDetection_en.properties)
File updated in new war(WEB-INF/classes/fmSAMLConfiguration_fr.properties)
...
Differences: 1821
Customizations: 3
{noformat}
This example shows the files that have been updated and customized in the new WAR file.
{anchor:ghona}
h1. Patching an OpenSSO Enterprise WAR File
Use this procedure to create a new staging area, where an original WAR file is merged with a new WAR file.
This operation compares the manifests for each WAR file and then shows:
* Files customized in the original WAR file
* Files updated in a new WAR file
* Files added or removed between the two WAR file versions
The {{ssopatch}} then copies the appropriate files to a staging directory, where you must add any customizations before you create and deploy the new patched WAR.
{anchor:ghotn}
h3. To Create a Staging Area to Patch an OpenSSO Enterprise WAR File
# Make sure that your {{JAVA_HOME}} environment variable points to JDK 1.5 or later and that the {{ssopatch}} utility is specified in your {{PATH}} variable.
# Although the {{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.
# Run {{ssopatch}} to create the staging area. For example:
{noformat}
./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
{noformat}
In this example, {{/tmp/staging}} is the staging area where {{ssopatch}} copies the files.
Update the files as needed in the staging-area, using the results of the previous step.
Use the following table to determine the action you might need to take for each file before you generate a new patched WAR file.
|| {{ssopatch}} Results || Explanation and Action Required ||
| {{File not in original war (_filename_)}} | The indicated file does not exist in the original WAR file but is in the latest version of the WAR file. \\
*Action*: None |
| {{File updated in new war (_filename_)}} | The indicated file exists in both the original and new WAR files and has been updated in the latest version of the WAR file. No customizations have been done in the original WAR file. \\
*Action*: None |
| {{File customized (_filename_)}} | The indicated file exists in both WAR files, has been customized in the original version of the WAR file, but has not been updated in the latest version of the WAR file. \\
*Action*: None |
| {{May require manual customization (_filename_)}} | The file exists in both WAR files, has been customized in the original version of the WAR file, and has been updated in the latest version of the WAR file. \\
*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. |
*Next Steps*
# Create a new OpenSSO Enterprise WAR file from the files in the staging area. For example:
{noformat}cd /tmp/staging
jar cvf /patched/opensso.war *
{noformat}where {{/patched/opensso.war}} is the name of the new patched OpenSSO Enterprise WAR file.
# Redeploy the {{/patched/opensso.war}} file to the web container using the original deploy URI. For example, {{/opensso}}
*OpenSSO configuration changes*. A new OpenSSO Enterprise WAR file might have configuration changes that were not in your original WAR file. Any configuration changes, if any, will be documented separately for each patch. Check the patch documentation and the [Release Notes|http://docs.sun.com/doc/820-3745] 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.)
If you need to back out your patched version, undeploy the patched WAR file and then redeploy your original WAR file.
{anchor:ghonx}
h1. Creating an OpenSSO Enterprise WAR Manifest File
An OpenSSO manifest file is a text file that identifies all of the individual files in a WAR file for a specific release, with checksum information for each file.
Use this procedure to create a manifest file that you can include in a specialized OpenSSO Enterprise WAR, such as an OpenSSO Enterprise server only, administration console only, Distributed Authentication UI server, or IDP Discovery Service WAR
{anchor:ghold}
h3. To Create an OpenSSO Enterprise WAR Manifest File
# Make sure that your {{JAVA_HOME}} environment variable points to JDK 1.5 or later and that the {{ssopatch}} utility is specified in your {{PATH}} variable.
# Run {{ssopatch}} to create the OpenSSO manifest file. For example:
{noformat}
./ssopatch -o zip-root/opensso/deployable-war/opensso.war --manifest /tmp/manifest
{noformat}
where {{opensso.war}} is an existing OpenSSO Enterprise WAR file.
The {{ssopatch}} utility creates a new manifest file named {{manifest}} in the the {{/tmp}} directory.
# To allow the WAR file to be patched, copy this new manifest file to the {{META-INF}} directory inside the {{opensso.war}} file. For example:
{noformat}mkdir META-INF
cp /tmp/manifest META-INF
jar uf opensso.war META-INF/manifest
{noformat}
{anchor:pasoewf}
h1. Patching a Specialized OpenSSO Enterprise WAR
If you have previously created a specialized OpenSSO Enterprise WAR, such as an OpenSSO Enterprise server only, administration console only, Distributed Authentication UI server, or IDP Discovery Service WAR, you can patch it by using the {{ssopatch}} utility.
h3. To Patch a Specialized OpenSSO Enterprise WAR
# Create a manifest file for your specialized OpenSSO Enterprise WAR, as described in [Creating an OpenSSO Enterprise WAR Manifest File|#ghonx].
*Note*: Create the manifest file based on the original OpenSSO Enterprise 8.0 {{opensso.war}}, as delivered from Sun, prior to any customizations you might have done. If the manifest is created after customizations, {{ssopatch}} might use the files from Update 1, rather than your customizations, so you would need to re-do your customizations after patching.
# Generate the specialized OpenSSO Enterprise WAR from the OpenSSO Enterprise 8.0 Update 1 ((opensso.war)) file, as described in [Creating a Specialized OpenSSO Enterprise 8.0 Update 1 WAR File|http://wikis.sun.com/x/JoYrBg].
# Use the {{ssopatch}} utility to compare the your old and new WAR files.
# Generate a staging area for the new specialized WAR file, as described in [Creating a Staging Area to Patch an OpenSSO Enterprise WAR File|#ghona].
{anchor:rtouss}
h1. 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 bug fixes and enhancements in Update 1. You must run {{updateschema}} in order to update the server version.
h4. Before You Begin
The {{updateschema.sh}} or {{updateschema.bat}} script requires the Update 1 version of the {{ssoadm}} command-line utility. Therefore, before you run this script, install the Update 1 admin tools, as described in [Installing the OpenSSO Enterprise 8.0 Update 1 Admin Tools|http://wikis.sun.com/x/tYF1BQ].
h4. To Run the {{updateschema}} Script
# Change to the {{{_}patch-tools_/patch}} directory, where {{{_}patch-tools{_}}} is where you unzipped {{ssoPatchTools.zip}}.
# Run {{updateschema.sh}} or {{updateschema.bat}}. For example, on Solaris systems:
{{./updateschema.sh}}
# 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.
h1. Backing Out a Patch Installation
If you need to back out your patch installation, simply redeploy the original {{opensso.war}} file (or specialized WAR file).
[Top of Page|#topofpage]
{column}
{column:width=25%}
{panel:title=Contents|titleBGColor=white|bgColor=white}
{toc:maxLevel=1}
{panel}
{column}
{section}