0a99555401a033704f1f171baab6db11fb5528f2Allan Foster DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Copyright (c) 2007 Sun Microsystems Inc. All Rights Reserved
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster The contents of this file are subject to the terms
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster of the Common Development and Distribution License
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster (the License). You may not use this file except in
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster compliance with the License.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster You can obtain a copy of the License at
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster https://opensso.dev.java.net/public/CDDLv1.0.html or
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster See the License for the specific language governing
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster permission and limitations under the License.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster When distributing Covered Code, include this CDDL
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Header Notice in each file and include the License file
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster If applicable, add the following below the CDDL Header,
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster with the fields enclosed by brackets [] replaced by
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster your own identifying information:
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster "Portions Copyrighted [year] [name of copyright owner]"
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster $Id: README.patch,v 1.2 2009/03/10 23:54:14 veiming Exp $
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterOpenSSO - Patch
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterNOTE: Patching of OpenSSO is only supported from an Enterprise build to an
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterExpress build. While these tools will allow you to update your customized
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosteropensso.war file to the latest nightly opensso.war (including your
0a99555401a033704f1f171baab6db11fb5528f2Allan Fostercustomizations), this should only be used in a test/development environment,
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterand should not be used to update a production system!
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterAlthough ssopatch does not make any changes to your existing war file, you should
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterbackup your war file prior to using this tool, to an archive location, so that
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterit can be recovered in case you ever need to revert your system to the previous
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterBefore setting up and running the OpenSSO Tools, the JAVA_HOME environment
0a99555401a033704f1f171baab6db11fb5528f2Allan Fostervariable needs to be initialized to a path of a compatible Java Runtime
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster(J2SE 1.5 or higher).
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterOpenSSO Patch Utility
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster=====================
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterssopatch is a Java application that will be included in each OpenSSO enterprise
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterand express built zip file, located in the tools subdirectory.
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterssopatch Usage
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster [--locale|-l]
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --war-file|-o
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster [--manifest|-m]
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster [--locale|-l]
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --war-file|-o
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --war-file-compare|-c
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster [--staging|-s]
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster [--locale|-l]
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster [--override|-r]
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster [--overwrite|-w]
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Print this usage. This is a unary option.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --war-file|-o
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Path to the WAR file. opensso.war file which has been previously
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --manifest|-m
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Path to manifest file to create. Manifest file will be generated from
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --war-file when this option is provided.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --war-file-compare|-c
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Path to the WAR file to compare against. It will be compared against
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --war-file when this option is provided.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --staging|-s
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Path to the staging area. Staging area where the files will be written.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --war-file-compare is compared against --war-file and the result will be
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster written to this directory.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Locale to be used. Default system locale is used if this is not set.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --overwrite|-w
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Option to overwrite existing staging area. This is a unary option.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Default is false.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster --override|-r
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Option to override revision checking. This is a unary option.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster Default is false.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterDefault usage: If only the the first argument is specified, ssopatch will
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster compare the contents of the specified war file against the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster manifest file stored inside of that war file, and report on the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster differences.
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterssopatch Use cases
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster------------------
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterThe patching utility has four functions: create a manifest file, compare a war
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterfile to its internal manifest, compare two war files, and generate a staging
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterCreate a Manifest File
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster----------------------
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterIf you acquired an opensso.war prior to Express build 5b, or if you are creating
0a99555401a033704f1f171baab6db11fb5528f2Allan Fostera customized war file (console only, distributed authentication, etc.), ssopatch
0a99555401a033704f1f171baab6db11fb5528f2Allan Fostercan be used to generate a manifest file which can be included in your war.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster% ssopatch --war-file "my.war" --manifest "OpenSSO.manifest"
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterThis will create a new file "OpenSSO.manifest" containing an entry for each file
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterin "my.war" with checksum information. After creating the manifest, if you want
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterto allow the war file to be patched, you should put the manifest file inside
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterCompare War Against Its Manifest
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster--------------------------------
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterIn order to determine if there were any customizations done to the original war
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterfile, ssopatch can be used. ssopatch will internally generate a new manifest
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterfile, then compare that internal manifest against the manifest stored inside the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster% ssopatch --war-file "my.war"
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterComparing manifest of Internal (Express Build 5(200810010552)) against
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster /my.war (generated-200810021026)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile not in original war (images/login-origimage.jpg)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile updated in new war (images/login-backimage.jpg)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile updated in new war (WEB-INF/classes/amConfigurator.properties)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterDifferences: 3
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterThe example shows:
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file images/login-origimage.jpg appears in my.war but was not found in
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster the manifest.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file images/login-backimage.jpg has been customized in my.war from the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster original manifest.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file WEB-INF/classes/amConfigurator.properties has been customized in
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster my.war from the original manifest.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterCompare Two War Files
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster---------------------
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterssopatch can be used to find out which files have been updated in a new war.
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterssopatch will internally generate a manifest file for the original war, generate
0a99555401a033704f1f171baab6db11fb5528f2Allan Fostera manifest for the new war, then compare the internal manifests against the
0a99555401a033704f1f171baab6db11fb5528f2Allan Fostermanifest stored inside the war file at META-INF/OpenSSO.manifest. This enables
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterus to show which files were customized inside the initial war, and which files
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterwere patched in the new war. It will also display any files that may have been
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosteradded or removed between the two versions.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster% ssopatch --war-file "my.war" --war-file-compare "new.war"
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterComparing manifest of my.war (generated-200810021042) against
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster new.war (generated-200810021042)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile not in original war (WEB-INF/classes/amClientDetection_en.properties)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile updated in new war (html/fr/help/policy.conditionadd.html)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterMay require manual customization (WEB-INF/classes/amConfigurator.properties)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterDifferences: 4190
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterCustomizations: 2
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterThe example shows:
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file WEB-INF/classes/amClientDetection_en.properties appears in new.war
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster but was not found in my.war.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file html/fr/help/policy.conditionadd.html appears in my.war but was
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file images/login-backimage.jpg has been customized in my.war from the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster original manifest, but was not changed in new.war.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file WEB-INF/classes/amConfigurator.properties has been customized in
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster my.war from the original manifest, but was also changed in new.war.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterCreate Staging Area
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster-------------------
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterssopatch can be used to create a new staging area, merging the original war file
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterwith the new war file. ssopatch will internally generate a manifest file for
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterthe original war, generate a manifest for the new war, then compare the internal
0a99555401a033704f1f171baab6db11fb5528f2Allan Fostermanifests against the manifest stored inside the war file at
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterMETA-INF/OpenSSO.manifest. This enables us to show which files were customized
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterinside the initial war, and which files were patched in the new war. It will
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosteralso display any files that may have been added or removed between the two
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterversions. It will output the appropriate files to a staging area, where the
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosteruser can finalize the customizations before creating the new patched war.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster% ssopatch --war-file="my.war" --war-file-compare "new.war" --staging "/staging"
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterComparing manifest of my.war (generated-200810021042) against
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster new.war (generated-200810021042)
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile customized. Staging area using original war version
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterMay require manual customization. Staging area using new war version
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterDifferences: 4190
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterCustomizations: 2
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterThe example shows:
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file images/login-backimage.jpg has been customized in my.war from the
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster original manifest, but was not changed in new.war. Since it had not been
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster changed between the old war manifest, and new war, we use the user
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster modifications in the staging area.
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster - the file WEB-INF/classes/amConfigurator.properties has been customized in
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster my.war from the original manifest, but was also changed in new.war. Since
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster it was customized, but also changed, we put the latest version in the staging
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster area, and the user will then have to manually re-enter their customizations.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterAfter the staging area has been updated, the user would then create the war
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterfile, and then redeploy the war file on their container.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterOpenSSOpatch Reporting
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster======================
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterssopatch will output the results to stdout. If the user wants to capture the
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosteroutput to a file, they can redirect it. ssopatch will output following results:
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile not in original war (filename) – file does not exist in orginal war, but is
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster in the latest version of the war.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile updated in new war (filename) – file exists in both war files, and has been
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster updated in the latest version of the war. No customizations have been done
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster in the original.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterFile customized (filename) – file exists in both war files, has been customized
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster in the original version of the war, but has not been updated in the latest
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster version of the war.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterMay require manual customization (filename) - file exists in both war files, has
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster been customized in the original version of the war, and has been updated in
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster the latest version of the war.
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterOpenSSOpatch Exit Codes
0a99555401a033704f1f171baab6db11fb5528f2Allan Foster=======================
0a99555401a033704f1f171baab6db11fb5528f2Allan FosterIf ssopatch finishes successfully, it will return a 0. For errors, a non-zero
0a99555401a033704f1f171baab6db11fb5528f2Allan Fosterexit code will be returned.