Sun Java Enterprise System 5 Update 1 Upgrade Guide for UNIX |
Chapter 12
Service RegistryThis chapter describes how to upgrade Service Registry to Java ES 5 Update 1 (Release 5U1): Service Registry 3.1 Update 1. It covers both feature upgrades from previous Java ES release families and maintenance upgrades from Java ES 5.
The chapter provides an overview of upgrade considerations for the different upgrade paths supported by Release 5U1. The chapter covers upgrades on both the Solaris and Linux operating systems:
Overview of Service Registry UpgradesThis section describes the following general aspects of Service Registry that impact upgrading to Java ES 5 Update 1 (Release 5U1):
About Release 5U1
Release 5U1 Service Registry is a maintenance release that fixes bugs in Release 5 Service Registry. Release 5 Service Registry was a minor feature release with respect to Release 4 Service Registry. It included some improved functionality, updated interfaces, and selected bug fixes.
Release 5U1 Upgrade Roadmap
Table 12-2 shows the supported Service Registry upgrade paths to Release 5U1. The table applies to both Solaris and Linux operating systems.
Service Registry Data
The following table shows the type of data that could be impacted by an upgrade of Service Registry software.
Service Registry Upgrade Strategy
Your strategy for upgrading Service Registry generally depends on the many considerations discussed in Chapter 1, "Planning for Upgrades": upgrade path, dependencies between Java ES components, selective upgrade versus upgrade all, multi-instance deployments, and so forth.
This section is to particularize that general discussion to Service Registry by presenting issues that might influence your Service Registry upgrade plan.
Compatibility Issues
Release 5U1 Service Registry is backwardly compatible with Release 4 and Release 5 Service Registry.
Dependencies
Service Registry dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Service Registry software. Changes in Service Registry interfaces or functions, for example, could require upgraded version of components upon which Service Registry depends. The need to upgrade such components depends upon the specific upgrade path.
Service Registry has dependencies on the following Java ES components:
- Shared components. Service Registry has dependencies on specific Java ES shared components (see Table 1-10).
- Application Server. Service Registry has a mandatory dependency on Application Server to provide a container for the Service Registry application and, in Java ES Release 5 and 5U1, to manage connections to the networked registry/repository database.
- Java DB. Service Registry has a mandatory dependency on Java DB as the default database for storing services and the meta data describing them.
Dual Upgrade
Dual upgrades, in which both Service Registry and operating system are upgraded (as described in Dual Upgrades: Java ES and Operating System Software) can be performed in either of two ways:
Fresh Operating System Installation
- Back up existing Service Registry data.
See Service Registry Data for the location of essential data.
- Install the new operating system.
The operating system installation can be on a new system (or a Solaris 10 zone) or it can wipe out the existing file system.
- Restore the Service Registry data that was backed up in Step 1.
- Install Release 5U1 Service Registry.
In-place Operating System Upgrade
- Back up existing Service Registry data.
See Service Registry Data for the location of essential data.
- Upgrade the operating system.
The upgrade leaves the existing file system in place.
- Upgrade to Release 5U1 Service Registry.
Upgrading Service Registry from Java ES 5This section includes information about upgrading Service Registry from Java ES 5 (Release 5) to Java ES 5 Update 1 (Release 5U1). The section covers the following topics:
Introduction
When upgrading Release 5 Service Registry to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is achieved by patching Release 5 Service Registry.
- Upgrade Dependencies. Service Registry has dependencies on a number of Java ES shared components (see Table 1-10), none of which need to be upgraded when you perform a maintenance upgrade of Service Registry.
- Backward Compatibility. Release 5UI Service Registry is backwardly compatible with the Release 5 version.
- Upgrade Rollback. A rollback of the Release 5U1 upgrade is achieved on Solaris OS by backing out the patch upgrade, but on the Linux platform rollback is achieved by manually reinstalling previous RPM packages.
- Platform Issues. The general approach for upgrading Service Registry is the same on both Solaris and Linux operating systems.
Release 5 Service Registry Upgrade
This section describes how to perform an upgrade of Service Registry from Java ES Release 5 to Release 5U1 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:
Pre-Upgrade Tasks
Before you upgrade Service Registry software you should perform the following tasks:
Verify Current Version Information
You can verify the current version of Service Registry by checking Service Registry package names and version numbers. For example:
On Solaris:
pkginfo -l | grep srvcOn Linux:
rpm -qa | grep srvcThe distinguishing package names and numbers are shown in the following table:
Upgrade Service Registry Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. Release 5U1 Service Registry has no hard upgrade dependencies. Upgrade of shared components is therefore optional.
Back Up Service Registry Data
The Service Registry upgrade from Release 5 to Release 5U1 does not modify configuration data or the registry/repository database. There is no need to back up current data.
Obtain Required Configuration Information and Passwords
You need to know the user IDs, passwords, domain name, and port number for your Release 5 Service Registry.
Upgrading Release 5 Service Registry (Solaris)
This section discusses considerations that impact the upgrade procedure for Service Registry, followed by a description of the procedure itself.
Upgrade Considerations (Solaris)
The upgrade of Service Registry software to Java ES Release 5U1 takes into account the following considerations:
- In a deployment architecture in which there are multiple instances of Service Registry running on a single computer (all corresponding to the same installed Service Registry image), you only have to upgrade the Service Registry image once.
- In a maintenance upgrade, you do not have to migrate schema, configuration, security or user data.
- In deployments in which the Service Registry client software only is installed on a computer (for example to support Portal Server), you only need to perform the steps in Upgrade Procedure (Solaris), below that involve the application of Service Registry patches. Steps 2, 3, 8, and 9 can be omitted.
- The Release 5U1 Service Registry upgrade patches for Solaris OS are shown in the following table:
Table 12-5 Patches1 to Upgrade Service Registry on Solaris
Description
Patch ID: SPARC
Solaris 9 & 10
Patch ID: X86
Solaris 9 & 10
Service Registry core
122810-09
122810-09
Service Registry localization
126292-03
126292-03
1Patch revision numbers are the minimum required for upgrade to Release 5U1. If newer revisions become available, use the newer ones instead of those shown in the table.
Upgrade Procedure (Solaris)
The procedure documented below applies to Service Registry instances residing locally on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- Make sure that the Jakarta ANT Java/XML-based build tool (ANT shared component) references the correct version of J2SE.
(The ant command is used in the steps that follow.)
PATH=/usr/jdk/entsys-j2se/bin:$PATH
export PATH
- Stop the Release 5 Service Registry (Application Server) domain.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml appserver.domain.stopThe domain is associated with a Service Registry instance.
- Make sure you have upgraded any Java ES components upon which Service Registry has hard upgrade dependencies (see Upgrade Service Registry Dependencies).
- Obtain the latest Service Registry upgrade patches, based on Table 12-5.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the appropriate Service Registry core and, if needed, localization patches in Table 12-5, in that order.
patchadd /workingDirectory/patch_ID
Be sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful:
showrev -p | grep patch_ID
The output should return the versions of patch IDs applied in Step 6.
- Upgrade and configure the Release 5U1 Service Registry instance.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml
-Dinstall.properties=ServiceRegistryR5-base/install/install.properties
upgrade.jes5.to.jes5u1- Start the Release 5U1 Service Registry (Application Server) domain.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f ./build-install.xml
appserver.domain.start appserver.deploy.testUpgrading Release 5 Service Registry (Linux)
This section discusses considerations that impact the upgrade procedure for Service Registry, followed by a description of the procedure itself.
Upgrade Considerations (Linux)
The upgrade of Service Registry software to Java ES Release 5U1 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that the Linux Release 5U1 upgrade patches differ from the Solaris patches.
The Release 5U1 Service Registry upgrade patches for Linux OS are shown in the following table:
Table 12-6 Patches1 to Upgrade Service Registry on Linux
Description
Patch ID and RPM names
Service Registry core
122811-09
Service Registry localization
126294-03
1Patch revision numbers are the minimum required for upgrade to Release 5U1. If newer revisions become available, use the newer ones instead of those shown in the table.
Upgrade Procedure (Linux)
The procedure documented below applies to Service Registry instances residing locally on the computer where the upgrade is taking place.
Caution
An upgrade from Release 5 to Release 5U1 on Linux cannot easily be rolled back. Locate the directory that contains the currently installed distribution before you begin.
- Log in as root or become superuser.
su -
- Make sure that the Jakarta ANT Java/XML-based build tool (ANT shared component) references the correct version of J2SE.
(The ant command is used in the steps that follow.)
PATH=/usr/jdk/entsys-j2se/bin:$PATH
export PATH
- Stop the Release 5 Service Registry (Application Server) domain.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml appserver.domain.stopThe domain is associated with a Service Registry instance.
- Make sure you have upgraded any Java ES components upon which Service Registry has hard upgrade dependencies (see Upgrade Service Registry Dependencies).
- Obtain the latest Service Registry upgrade patches, based on Table 12-6.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the core and, if needed, localization patch for Service Registry in Table 12-6, in that order.
rpm -Fvh *.rpm
Be sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful.
rpm -qa | grep sun-srvc
The new version numbers of the RPMs should be returned.
- Upgrade and configure the Release 5U1 Service Registry instance.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml
-Dinstall.properties=ServiceRegistryR5-base/install/install.properties
upgrade.jes5.to.jes5u1- Start the Release 5U1 Service Registry (Application Server) domain.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f ./build-install.xml
appserver.domain.start appserver.deploy.testVerifying the Upgrade
You can verify successful upgrade of Service Registry by checking Service Registry package names and version numbers. For example:
On Solaris:
pkginfo -l | grep srvcOn Linux:
rpm -qa | grep srvcThe distinguishing package names and numbers are shown in Table 12-4.
Post-Upgrade Tasks
There are no post-upgrade tasks beyond the steps described in Upgrade Procedure (Solaris) and Upgrade Considerations (Linux).
Rolling Back the Upgrade (Solaris)
This section describes the Release 5U1 upgrade rollback procedure for Service Registry on the Solaris platform.
- Log in as root or become superuser.
su -
- Stop the Release 5 Service Registry (Application Server) domain.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml appserver.domain.stopThe domain is associated with a Service Registry instance.
- Remove the patches in Table 12-5.
patchrm patch_ID
- Execute the following command:
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f ./build-install.xml appserver.domain.start appserver.undeploy appserver.deploy appserver.deploy.fix
install.l10n appserver.domain.stop appserver.domain.start
appserver.deploy.testRolling Back the Upgrade (Linux)
This section describes the Release 5U1 upgrade rollback procedure for Service Registry on the Linux platform. There is no automated rollback procedure for Linux patches, so the recommended approach is to manually overwrite the Release 5U1 RPMs with the Release 5 RPMs, as described below.
- Log in as root or become superuser.
su -
- Stop the Release 5 Service Registry (Application Server) domain.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml appserver.domain.stopThe domain is associated with a Service Registry instance.
- Check the revision numbers of Service Registry RPMs.
rpm -qa | grep sun-srvc
The updated RPMs should be those listed in Table 12-6.
- Check to see if the RPMs have been relocated from their default location.
rpm -q --queryformat '%{INSTALLPREFIX}' rpmName
where rpmName is the unique name of the RPM (for example, the values sun-srvc-* shown in Table 12-6). The command returns a prefixValue as a path to the installed RPM.
- Reinstall Release 5 RPMs from the Java ES 5 distribution.
(If you are rolling back to a post-Release 5 sustaining patch, rather than to Release 5, reinstall the RPMs from that patch.)
rpm -Uvh --force [--prefix prefixValue] *.rpm
The --force option will allow the command to overwrite later packages of the same name. The --prefix option is not required unless the RPMs have been relocated. (If only a subset of the RPMs had been relocated, use individual file names as command arguments rather than *.rpm.)
- Execute the following command:
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f ./build-install.xml appserver.domain.start appserver.undeploy appserver.deploy appserver.deploy.fix
install.l10n appserver.domain.stop appserver.domain.start
appserver.deploy.testMultiple Instance Upgrades
In some deployment architectures Service Registry is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Service Registry instances running on multiple computers with a load balancer to distribute the load.
In these architectures the registries are predominantly read-only and respond to a heavy query load by accessing a common database.
You perform the upgrade of Service Registry on each computer as described in Release 5 Service Registry Upgrade.
Upgrading Service Registry from Java ES Release 4This section includes information about upgrading Service Registry from Java ES 2005Q4 (Release 4) to Java ES 5 Update 1 (Release 5U1). The section covers the following topics:
Introduction
When upgrading Java ES Release 4 Service Registry to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is achieved by performing a fresh install of Release 5U1 Service Registry, migrating the Release 4 data and configuration to Release 5U1, and then removing Release 4 to conserve disk space.
- Upgrade Dependencies. Service Registry has dependencies on a number of Java ES shared components (see Table 1-10), all of which are automatically upgraded to Release 5U1 by the Java ES installer when you perform an upgrade of Service Registry.
- Backward Compatibility. Release 5U1 Service Registry is fully compatible with Release 4.
- Upgrade Rollback. A rollback of the Release 5U1 upgrade is achieved by reverting to Release 4 after restoring the saved database and configuration data.
- Platform Issues. The general approach for upgrading Service Registry is the same on both Solaris and Linux operating systems.
Release 4 Service Registry Upgrade
This section describes how to perform an upgrade of Service Registry from Java ES Release 4 to Release 5U1 on both the Solaris and Linux platforms. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:
Pre-Upgrade Tasks
Before you upgrade Service Registry, you should perform the following tasks:
Verify Current Version Information
You can verify the current version of Service Registry by checking Service Registry package names and version numbers. For example:
On Solaris:
pkginfo -l | grep srvcOn Linux:
rpm -qa | grep srvcThe distinguishing package names and numbers are shown in Table 12-4.
Upgrade Service Registry Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. Service Registry has hard upgrade dependencies on a number of shared components, Application Server, and Java DB.
When upgrading Service Registry dependencies, you should do so in the order below (skipping any that might already have been upgraded), before you upgrade Service Registry. Upgrade of shared components is normally achieved automatically by the Java ES installer.
- Shared Components. Instructions for synchronizing Java ES shared components to Release 5U1 are provided in Upgrading Java ES Shared Components. However, all shared components required by Service Registry are upgraded automatically by the Java ES installer when you perform an upgrade of Service Registry to Release 5U1.
- Java DB. Instructions for upgrading Java DB to Release 5U1 are provided in Chapter 8, "Java DB".
- Application Server. Instructions for upgrading Application Server to Release 5U1 are provided in Chapter 11, "Application Server".
Modify the HTTP Port Number
Edit the ServiceRegistryR4-base/install/install.properties file to change the HTTP port from 6060 to 6480 (6060 is a reserved port). For information on setting this property, see the Service Registry 3.1Update 1 Administration Guide, http://docs.sun.com/doc/819-1596.
Back Up Service Registry Data
The Service Registry upgrade from Release 4 to Release 5U1 does not modify configuration data or the registry/repository database. There is no need to back up current data.
Obtain Required Configuration Information and Passwords
You need to know the user IDs, passwords, domain name, and port number for your Release 4 Service Registry.
Upgrading Release 4 Service Registry
This section describes the upgrade procedure on Solaris and Linux platforms.
Upgrade Procedure (Solaris)
The procedure documented below applies to Service Registry instances residing locally on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- Make sure that the Jakarta ANT Java/XML-based build tool (ANT shared component) references the correct version of J2SE.
(The ant command is used in the steps that follow.)
PATH=/usr/jdk/entsys-j2se/bin:$PATH
export PATH
- Stop the Release 4 Service Registry (Application Server) domain.
cd ServiceRegistryR4-base/install
/usr/sfw/bin/ant -f build-install.xml appserver.domain.stopThe domain is associated with a Service Registry instance.
- Perform a fresh install of Release 5U1 Service Registry.
Perform the following steps:
- Launch the Java ES installer on the computer hosting Release 4 Service Registry.
cd Java ES Release 5U1 distribution/os_arch
./installerwhere os_arch matches your platform, such as Solaris_sparc. (Use the installer -nodisplay option for the command line interface.)
After the Welcome and License Agreement pages are displayed, you will be presented with a component selection page. (When installed components are detected that can be directly upgraded by the Java ES installer, they are shown with a status of "upgradable.")
- Select Service Registry from the component selection page.
- Specify an installation directory path different from that of Release 4.
By default, the Release 5U1 installation path (ServiceRegistryR5-base) is different from the Release 4 installation path (ServiceRegistryR4-base).
- Select the Configure Later option.
Configure Now is not supported.
- If needed, select the option to install localized packages.
- Exit the Java ES installer when installation is complete.
- Apply the latest Service Registry maintenance patches, if any.
- Check if there have been any Service Registry point fixes subsequent to Release 5U1.
Periodically obtain the latest patches as described in Accessing Java ES Patches and compare them to the Release 5U1 patch revision numbers shown in Table 12-5 (Solaris) or Table 12-6 (Linux).
If you are using Sun Connection on the Solaris platform, you are automatically notified of new patches for Java ES components installed on your computer.
- Apply the appropriate Service Registry core and, if needed, localization patches in that order.
On Solaris:
patchadd /workingDirectory/patch_IDIf you are using the accumulated patch cluster on the Solaris platform, the install_cluster script will apply any Java ES patches needed on your computer.
On Linux:
rpm -Fvh *.rpmBe sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful:
On Solaris:
showrev -p | grep patch_IDOn Linux:
rpm -qa | grep sun-srvcThe output should return the appropriate patch IDs or version numbers.
- Upgrade and configure the Release 5U1 Service Registry instance.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml
-Dinstall.properties=ServiceRegistryR4-base/install/install.properties
upgradeAs an alternative to pointing to the Release 4 install.properties file, you can modify the default Release 5U1 install.properties file to reproduce any Release 4 property values. For information on setting these properties, see the Service Registry 3.1Update 1 Administration Guide, http://docs.sun.com/doc/819-1596.
If you are using custom property values, but not putting them in install.properties, then you need to specify such property values on the Ant command line (all on one line), as follows:
/usr/sfw/bin/ant -f build-install.xml
-Dregistry.install.RegistryServerKeystorePassword=passwd1
-Dregistry.install.AdministratorPassword=passwd2
-Dregistry.install.ApplicationServerKeystorePassword=passwd3
upgradeHowever, it is recommended that you include such custom property values in the install.properties file with restricted permissions to avoid the use of command-line settings that can be viewed by unauthorized personnel. See the Service Registry Administration Guide for more information.
The upgrade utility creates a new Application Server domain, starts the domain, and deploys the Service Registry instance in the domain. Each Service Registry instance is associated with its own Application Server domain.
- If the server property files of the Release 4 Service Registry have been modified, you can make corresponding changes to the Release 5U1 Service Registry configuration as follows:
- Stop the Release 5U1 Service Registry (Application Server) domain.
(The domain was automatically started by the upgrade command of Step 6.)
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml appserver.domain.stop- Transfer the Release 4 Service Registry instance configuration to Release 5U1.
Add any modifications that you had made to the Release 4 Service Registry instance configuration:
RegistryDomainR4-base/domains/registry/applications/j2ee-modules/
soar/WEB-INF/classes/*.propertiesto the corresponding Release 5U1 configuration:
RegistryDomainR5-base/domains/registry/applications/j2ee-modules/
soar/WEB-INF/classes/*.properties- Start the Release 5U1 Service Registry (Application Server) domain.
cd ServiceRegistryR5-base/install
/usr/sfw/bin/ant -f build-install.xml appserver.domain.startUpgrade Procedure (Linux)
Upgrading Service Registry on Linux is identical to Solaris (see Upgrade Procedure (Solaris)) except that the location of the ant command on the Linux platform, which is used in various steps of the upgrade procedure, is different from the location on Solaris platforms:
Verifying the Upgrade
You can verify successful upgrade of Service Registry by checking Service Registry package names and version numbers. For example:
On Solaris:
pkginfo -l | grep srvcOn Linux:
rpm -qa | grep srvcThe distinguishing package names and numbers are shown in Table 12-4.
Post-Upgrade Tasks
The following steps, which describe how to remove Release 4 Service Registry, should not be performed until you are certain you do not want to roll back the upgrade to Release 4.
- Delete the Release 4 Service Registry (Application Server) domain:
cd ServiceRegistryR4-base/install
On Solaris:
/usr/sfw/bin/ant -f build-install.xml appserver.domain.deleteOn Linux:
/opt/sun/bin/ant -f build-install.xml appserver.domain.delete- Delete the directory containing the Release 4 Service Registry domain files.
rm -rf RegistryDomainR4-base
- Delete the directory containing the Release 4 Service Registry installation files.
rm -rf ServiceRegistryR4-base
Rolling Back the Upgrade
A rollback of the Release 5U1 upgrade is achieved by reverting to the previous version, which is left intact by the upgrade to Release 5U1.
- Stop and delete the Release 5U1 Service Registry (Application Server) domain:
cd ServiceRegistryR5-base/install
On Solaris:
/usr/sfw/bin/ant -f build-install.xml appserver.domain.deleteOn Linux:
/opt/sun/bin/ant -f build-install.xml appserver.domain.delete- Run the Java ES Release 5U1 uninstaller to uninstall Release 5U1 Service Registry.
- Start the Release 4 Service Registry domain.
cd ServiceRegistryR4-base/install
On Solaris:
/usr/sfw/bin/ant -f build-install.xml appserver.domain.startOn Linux:
/opt/sun/bin/ant -f build-install.xml appserver.domain.start- Access the Release 4 Service Registry Web Console.
http://localhost:6480/soar
- Confirm that the Console displays Release 4 characteristics as shown in Service Registry Version Verification Outputs.
Multiple Instance Upgrades
In some deployment architectures Service Registry is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Service Registry instances running on multiple computers with a load balancer to distribute the load.
In these architectures the registries are predominantly read-only and respond to a heavy query load by accessing a common database.
You perform the upgrade of Service Registry on each computer as described in Release 4 Service Registry Upgrade.