DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. Copyright (c) 2007 Sun Microsystems Inc. All Rights Reserved The contents of this file are subject to the terms of the Common Development and Distribution License (the License). You may not use this file except in compliance with the License. You can obtain a copy of the License at See the License for the specific language governing permission and limitations under the License. When distributing Covered Code, include this CDDL Header Notice in each file and include the License file If applicable, add the following below the CDDL Header, with the fields enclosed by brackets [] replaced by your own identifying information: "Portions Copyrighted [year] [name of copyright owner]" NOTE: Patching of OpenSSO is only supported from an Enterprise build to an
Express build. While these tools will allow you to update your customized
customizations), this should only be used in a
test/
development environment,
and should not be used to update a production system!
Although ssopatch does not make any changes to your existing war file, you should
backup your war file prior to using this tool, to an archive location, so that
it can be recovered in case you ever need to revert your system to the previous
Before setting up and running the OpenSSO Tools, the JAVA_HOME environment
variable needs to be initialized to a path of a compatible Java Runtime
ssopatch is a Java application that will be included in each OpenSSO enterprise
and express built zip file, located in the tools subdirectory.
Print this usage. This is a unary option.
Path to the WAR file.
opensso.war file which has been previously
Path to manifest file to create. Manifest file will be generated from
--war-file when this option is provided.
Path to the WAR file to compare against. It will be compared against
--war-file when this option is provided.
Path to the staging area. Staging area where the files will be written.
--war-file-compare is compared against --war-file and the result will be
written to this directory.
Locale to be used. Default system locale is used if this is not set.
Option to overwrite existing staging area. This is a unary option.
Option to override revision checking. This is a unary option.
Default usage: If only the the first argument is specified, ssopatch will
compare the contents of the specified war file against the
manifest file stored inside of that war file, and report on the
The patching utility has four functions: create a manifest file, compare a war
file to its internal manifest, compare two war files, and generate a staging
If you acquired an
opensso.war prior to Express build 5b, or if you are creating
a customized war file (console only, distributed authentication, etc.), ssopatch
can be used to generate a manifest file which can be included in your war.
This will create a new file "
OpenSSO.manifest" containing an entry for each file
in "
my.war" with checksum information. After creating the manifest, if you want
to allow the war file to be patched, you should put the manifest file inside
Compare War Against Its Manifest
--------------------------------
In order to determine if there were any customizations done to the original war
file, ssopatch can be used. ssopatch will internally generate a new manifest
file, then compare that internal manifest against the manifest stored inside the
% ssopatch --war-file "
my.war"
Comparing manifest of Internal (Express Build 5(200810010552)) against
/
my.war (generated-200810021026)
my.war from the original manifest.
ssopatch can be used to find out which files have been updated in a new war.
ssopatch will internally generate a manifest file for the original war, generate
a manifest for the new war, then compare the internal manifests against the
us to show which files were customized inside the initial war, and which files
were patched in the new war. It will also display any files that may have been
added or removed between the two versions.
Comparing manifest of
my.war (generated-200810021042) against
original manifest, but was not changed in
new.war.ssopatch can be used to create a new staging area, merging the original war file
with the new war file. ssopatch will internally generate a manifest file for
the original war, generate a manifest for the new war, then compare the internal
manifests against the manifest stored inside the war file at
inside the initial war, and which files were patched in the new war. It will
also display any files that may have been added or removed between the two
versions. It will output the appropriate files to a staging area, where the
user can finalize the customizations before creating the new patched war.
% ssopatch --war-file="
my.war" --war-file-compare "
new.war" --staging "/staging"
Comparing manifest of
my.war (generated-200810021042) against
File customized. Staging area using original war version
May require manual customization. Staging area using new war version
original manifest, but was not changed in
new.war. Since it had not been
changed between the old war manifest, and new war, we use the user
modifications in the staging area.
my.war from the original manifest, but was also changed in
new.war. Since
it was customized, but also changed, we put the latest version in the staging
area, and the user will then have to manually re-enter their customizations.
After the staging area has been updated, the user would then create the war
file, and then redeploy the war file on their container.
ssopatch will output the results to stdout. If the user wants to capture the
output to a file, they can redirect it. ssopatch will output following results:
File not in original war (filename) – file does not exist in orginal war, but is
in the latest version of the war.
File updated in new war (filename) – file exists in both war files, and has been
updated in the latest version of the war. No customizations have been done
File customized (filename) – file exists in both war files, has been customized
in the original version of the war, but has not been updated in the latest
May require manual customization (filename) - file exists in both war files, has
been customized in the original version of the war, and has been updated in
the latest version of the war.
If ssopatch finishes successfully, it will return a 0. For errors, a non-zero
exit code will be returned.