Oracle® OpenSSO 8.0 Update 2 Release Notes Release 8.0 Part Number E28339-03 |
|
|
View PDF |
This chapter describes how to install Oracle OpenSSO Update 2.
This chapter includes the following sections:
OpenSSO 8.0 Update 2 is available as a patch at the following URL:
http://www.oracle.com/technetwork/middleware/downloads/oid-11g-161194.html
Before you install OpenSSO 8.0 Update 2 (or subsequent patches), check the information about new features, hardware and software requirements, and issues and workarounds in this document.
OpenSSO 8.0 Update 2 includes an opensso.war
file that you can install using these methods:
Patch an existing OpenSSO 8.0 deployment: Use the ssopatch
utility in Update 2 to patch an existing OpenSSO 8.0 deployment, as described in this chapter.
Note - Oracle supports patching only OpenSSO 8.0 releases. For example, patching OpenSSO 8.0 with OpenSSO 8.0 Update 2 is supported.
Install a new OpenSSO 8.0 Update 2 deployment: Install and configure the OpenSSO 8.0 Update 2 opensso.war
file, as described in the Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
Create a new specialized WAR file: Use the createwar
script to create one of the following new WAR files from the Update 2 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 Chapter 4, Creating a Specialized OpenSSO Enterprise 8.0 Update 1 WAR File, in Sun OpenSSO Enterprise 8.0 Update 1 Release Notes.
Patch an existing specialized OpenSSO WAR file: Use the ssopatch
utility in Update 2 to patch an existing specialized OpenSSO 8.0 WAR file, as described inChapter 23, Patching OpenSSO Enterprise 8.0, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide
Note:
If you are running Access Manager 7.1 or Access Manager 7 2005Q4 and you want to upgrade to Update 2, follow these steps:
Upgrade Access Manager 7.x to OpenSSO 8.0, as described in Sun OpenSSO Enterprise 8.0 Upgrade Guide.
Apply the Update 2 patch, as described in this chapter.
Sun periodically releases patches for OpenSSO 8.0 Update 2. For information about these patches, check back here periodically.
Read the Overview of the ssopatch
Utility.
Install the patch utility for your platform, as described in Installing the ssopatch
Utility.
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 WAR File to Its Internal Manifest.
Compare your existing WAR file and the Update 2 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 WAR Files.
Backup and archive your existing Opensso WAR file, as described in Backing Up an OpenSSO WAR File.
Patch your OpenSSO WAR File, as described in Patching an OpenSSO WAR File.
Run the updateschema
script, as described in Running the updateschema
Script.
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 WAR.
ssopatch
UtilityThe 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 8.0 Update 2 has changed considerably since the OpenSSO 8.0 release. For the new syntax, see Running the updateschema
Script.
The ssopatch
patch utility performs these functions:
Compares an OpenSSO WAR to its original manifest, to determine if the WAR file has been customized or modified
Compare two OpenSSO 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 WAR file
After you download and unzip the OpenSSO 8.0 Update 2 ZIP file (oracle_opensso_80U2.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 oracle_opensso_80U2.zip
.
The ssopatch
utility uses a manifest file to determine the contents of a specific OpenSSO WAR file. A manifest file is an ASCII text file that contains:
A string that identifies the specific version of the OpenSSO WAR file
All of the individual files in the OpenSSO 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 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.
ssopatch
UtilityBefore you install the ssopatch
utility:
Download and unzip the OpenSSO 8.0 Update 2 ZIP file (oracle_opensso_80U2.zip
).
Set your JAVA_HOME
environment variable point to JDK 1.5 or later.
ssopatch
UtilityLocate the ssoPatchTools.zip
file in the zip-root
/opensso/tools
directory, where zip-root
is where you unzipped oracle_opensso_80U2.zip
.
Create a new directory to unzip the ssoPatchTools.zip
file. For example: ssopatchtools
Unzip the ssoPatchTools.zip
file in the new directory.
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 file that describes |
|
Required |
|
|
|
Required properties files |
|
Utilities for Solaris, Linux, and Windows systems |
Before you begin, backup your existing OpenSSO WAR file and configuration data:
Copy your existing OpenSSO WAR file to a safe location. Then, if you need to back out Update 2 for some reason, you can re-deploy your backup copy of the WAR file.
Backup your configuration data, as described in Chapter 15, Backing Up and Restoring Configuration Data, in Sun OpenSSO Enterprise 8.0 Administration Guide.
ssopatch
Utilityssopatch
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:
-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 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).
Use this procedure to determine if an OpenSSO 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 WAR file in the META-INF
directory.
Run ssopatch
to compare the OpenSSO WAR file to its internal manifest. For example:
./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
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.
Use this procedure to compare two WAR files, to show the files that have been:
Customized in an original OpenSSO WAR
Updated in a new OpenSSO WAR file
Added or deleted between the two OpenSSO WAR versions
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:
./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 2 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
This example shows the files that have been updated and customized in the new 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.
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:
./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 2 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.
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 |
---|---|
|
The indicated file does not exist in the original WAR file but is in the latest version of the WAR file. Action: None |
|
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 |
|
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 |
|
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. |
|
The file existed in the original WAR file, but is not in the new WAR. Action: None. |
Next Steps
Create a new OpenSSO 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 new patched OpenSSO 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 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 Sun OpenSSO Enterprise 8.0 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.)
If you need to back out your patched version, undeploy the patched WAR file and then redeploy your original WAR 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 WAR, such as an OpenSSO server only, administration console only, Distributed Authentication UI server, or IDP Discovery Service WAR
Run ssopatch
to create the OpenSSO manifest file. For example:
./ssopatch -o zip-root/opensso/deployable-war/opensso.war --manifest /tmp/manifest
where opensso.war
is an existing OpenSSO 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:
mkdir META-INF cp /tmp/manifest META-INF jar uf opensso.war META-INF/manifest
If you have previously created a specialized OpenSSO WAR, such as an OpenSSO server only, administration console only, Distributed Authentication UI server, or IDP Discovery Service WAR, you can patch it by using the ssopatch
utility.
Before You Begin
The existing specialized WAR file and the OpenSSO 8.0 update 2 specialized WAR file should already be created.
Note:
In the following example, the directory zip-root
is the root directory for the unzipped contents of the currently deployed WAR file. The directory /u2
is the root directory for the unzipped contents of the upgraded version that will be deployed.
Create a manifest file for the existing specialized OpenSSO WAR.
Run ssopatch
to create the OpenSSO manifest file.
Example:
# cd /u2/opensso/tools/patch # ./ssopatch -o zip-root/opensso/deployable-war/distauth.war --manifest /tmp/OpenSSO.manifest
where opensso.war
is an existing OpenSSO WAR file. The ssopatch
utility creates a new manifest file named manifest
in 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.
Example:
# cd zip-root/opensso/deployable-war # mkdir META-INF # cp /tmp/OpenSSO.manifest META-INF # jar uf distauth.war META-INF/OpenSSO.manifest # rm -rf /tmp/OpenSSO.manifest
Generate a manifest file for the updated specialized WAR file.
Example:
# cd /u2/opensso/tools/patch # ./ssopatch -o /u2/opensso/deployable-war/distauth.war --manifest /tmp/OpenSSO.manifest cd ../../deployable-war # mkdir META-INF # cp /tmp/OpenSSO.manifest META-INF # jar uf distauth.war META-INF/OpenSSO.manifest # rm -rf /tmp/OpenSSO.manifest
Use the ssopatch
utility to compare your old and new WAR files.
Example:
# cd /u2/opensso/tools/patch # ./ssopatch -o zip-root/opensso/deployable-war/distauth.war -c /u2/opensso/deployable-war/distauth.war -override
Generate a staging area for the new specialized WAR file.
Example:
# cd /tmp/customized_staging # jar cvf /patched/distauth.war *
Redeploy the /patched/distauth.war file to the web container using the original deploy URI.
Example,/distauth
.
updateschema
ScriptAfter you run ssopatch
, run the updateschema.sh
on Solaris or Linux systems or updateschema.bat
on Windows. The script updates the OpenSSO server version, adds new default server properties, adds new attribute schemas required for bug fixes and enhancements in Update 2. You must run updateschema
in order to update the server version.
The updateschema.sh
or updateschema.bat
script requires the Update 2 version (or later) of the ssoadm
command-line utility. Therefore, before you run this script, install the Update 2 admin tools, as described in Chapter 3, Installing the OpenSSO Enterprise 8.0 Update 1 Admin Tools, in Sun OpenSSO Enterprise 8.0 Update 1 Release Notes.
The updateschema.bat
script executes several ssoadm
commands. Therefore, before you run updateschema.bat
on Windows systems, create a password file that contains the password user in clear text for the amadmin
user. The updateschema.bat
script prompts you for the path to the password file. Before the script terminates, it removes the password file.
updateschema
ScriptChange to the patch-tools
/patch
directory, where patch-tools
is where you unzipped ssoPatchTools.zip
.
Caution:
You must run the updateschema
script from this directory. Otherwise, the script can fail and leave partially updated LDAP data and configuration files. If the script fails with a partial update, you must restore the data and configuration files from backup copies.
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.
Restart the OpenSSO 8.0 Update 2 web container.
If you need to back out your patch installation, simply redeploy the original opensso.war
file (or specialized WAR file).