|
| |
| Sun Java Enterprise System 5 Update 1 Upgrade Guide for UNIX | |
Chapter 15
Portal ServerThis chapter describes how to upgrade Portal Server to Java ES 5 Update 1 (Release 5U1): Sun Java System Portal Server 7.1U2. 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 Portal Server UpgradesThis section describes the following general aspects of Portal Server that impact upgrading to Java ES 5 Update 1 (Release 5U1):
About Release 5U1 Portal Server
Release 5U1 Portal Server is a maintenance release that fixes bugs in Release 5 Portal Server. Release 5 Portal Server was a feature release, with many new enhancements and features with respect to Release 4.
Many of these changes were made in an Interim Feature Release (IFR) subsequent to Release 4. Release 5U1 therefore represents only minor feature changes with respect to the IFR. For information about the IFR enhancements and new features, see the Sun Java System Portal Server 7.1 Release Notes, http://docs.sun.com/doc/819-4986/6n4l3f365?a=view. In particular, the Release 4 command line administrative interface was replaced by the psadmin command.
Portal Server Upgrade Roadmap
Table 15-2 shows the supported Portal Server upgrade paths to Release 5U1. The table applies to both Solaris and Linux operating systems.
Portal Server Data
The following table shows the type of data that could be impacted by an upgrade of Portal Server software.
Portal Server Upgrade Strategy
Your strategy for upgrading Portal Server 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 Portal Server by presenting issues that might influence your Portal Server upgrade plan.
Compatibility Issues
Release 5 Portal Server introduced public interface changes in the psadmin command used to administer Portal Server and Portal Server Secure Remote Access components. See the Sun Java System Portal Server 7.1 Command-Line Reference, http://docs.sun.com/doc/819-5030.
Hence, Release 5 and Release 5U1 Portal Server is not backwardly compatible with earlier versions, or with earlier versions of Portal Server Secure Remote Access components (including the SRA Gateway, the Rewriter Proxy, and the Netlet Proxy), except for a transitional period in which multi-instance deployments are undergoing a rolling upgrade. All Portal Server instances need to be synchronized, along with Portal Server Secure Remote Access component instances, at Release 5U1.
Also, individual Portal Server components, including the mobile access component, are not backwardly compatible with earlier versions; all need to be synchronized to Release 5U1.
In addition, there is an incompatibility between the Directory Server data structures used by Release 5 and Release 5U1 Portal Server and earlier Portal Server versions. This incompatibility impacts a rolling upgrade of multiple Portal Server instances using the same Directory Server data.
Portal Server Dependencies
Portal Server dependencies on other Java ES components can impact your procedure for upgrading and re-configuring Portal Server software. Changes in Portal Server interfaces or functions, for example, could require upgraded version of components upon which Portal Server depends. The need to upgrade such components depends upon the specific upgrade path.
Portal Server has dependencies on the following Java ES components:
- Shared components. Portal Server has dependencies on specific Java ES shared components (see Table 1-10).
- Web Container. Portal Server has a mandatory dependency on web container services, which can be provided either by Java ES Web Server or Java ES Application Server.
- Access Manager (or Access Manager SDK). Portal Server has a mandatory dependency on Access Manager to provide authentication and authorization services for end users, including single sign-on. If Access Manager is run on a remote computer, then Access Manager SDK must be available locally.
- Directory Server. Portal Server has a mandatory dependency on Directory Server, which stores user data accessed by way of Access Manager. As a result, Portal Server upgrades might require extensions of directory schema.
- Portal Server Secure Remote Access. Portal Server has an optional dependency on Portal Server Secure Remote Access, which provides secure remote access through the Gateway, Rewriter Proxy, and Netlet Proxy components.
- Java DB. Portal Server has an optional dependency on Java DB, which provides support for several portlet applications.
- Service Registry. Portal Server has a mandatory dependency on Service Registry, which provides libraries needed for compilation.
- Communications Express. Portal Server has an optional dependency on Communications Express, a Sun Java Communications Suite component, which is used to provide messaging and calendar channels to end users. Communications Express is no longer a Java ES product component.
Selective Upgrade Issues
While, in general, Java ES 5 Update 1 supports selective upgrade of all components on a computer, the fact that Portal Server has dependencies on so many other Java ES components makes it very difficult to certify arbitrary combinations of components across various Java ES release versions.
For this reason, Portal Server supports a restricted set of upgrade scenarios with respect to Access Manager and web containers.
- If you are upgrading Portal Server from Release 5. You can either upgrade Directory Server, Access Manager, and web container (Web Server or Application Server) to Release 5U1 before upgrading Portal Server, or you can upgrade only Portal Server to Release 5U1 (leaving the other components at their Release 5 levels), but you cannot leave some dependencies at Release 5 and upgrade others to Release 5U1.
- If you are upgrading Portal Server from Java ES Release 4. You can either upgrade Directory Server, Access Manager, and web container (Web Server or Application Server) to Release 5U1 before upgrading Portal Server, or you can upgrade only Portal Server to Release 5U1 (leaving the other components at their Release 4 levels), but you cannot leave some dependencies at Release 4 and upgrade others to Release 5U1.
- If you are upgrading Portal Server from Java ES Release 3. You have to upgrade Directory Server, Access Manager, and web container (Web Server or Application Server) to Release 4 or to Release 5U1 before upgrading Portal Server, but you cannot leave any dependencies at Release 3, nor upgrade some dependencies to Release 4 and others to Release 5U1.
- If you are upgrading Portal Server from Java ES Release 2. You have to upgrade Directory Server, Access Manager, and web container (Web Server or Application Server) to Release 4 or to Release 5U1 before upgrading Portal Server. You cannot leave any dependencies at Release 2, nor upgrade some dependencies to Release 4 and others to Release 5U1.
Web Container Upgrade Scenarios
Portal Server can be deployed in a web container provided by either Web Server or Application Server. As a result, the upgrade of Portal Server to Release 5U1 can be complicated by the possibility of also having upgraded to Release 5U1 the web container in which it is deployed. In this regard, there are a number of web container upgrade scenarios possible, enumerated in the following table.
You must be careful when upgrading Portal Server (for example when using the psupgrade script) to provide values appropriate to the upgrade scenario in Table 15-4 that applies, especially in scenarios for which there is a major version upgrade of the web container.
Dual Upgrade
Dual upgrades, in which both Portal Server and operating system are upgraded (as described in Dual Upgrades: Java ES and Operating System Software) can be performed using the in-place operating system upgrade approach:
- Back up existing Portal Server data.
See Portal Server Data for the location of essential data.
- Upgrade the operating system.
The upgrade leaves the existing file system in place.
- Upgrade to Release 5U1 Portal Server.
See the appropriate section of this chapter, depending on upgrade path.
Upgrading Portal Server from Java ES 5This section includes information about upgrading Portal Server 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 Portal Server to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is achieved by patching Release 5 Portal Server and running a psupdate script.
- Upgrade Dependencies. Portal Server 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 Portal Server.
- Backward Compatibility. Release 5UI Portal Server 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 Linux rollback can be achieved only if you have manually backed up the Release 5 image and then revert back to that image.
- Platform Issues. The general approach for upgrading Portal Server is the same on both Solaris and Linux operating systems.
Release 5 Portal Server Upgrade
This section describes how to perform an upgrade of Portal Server 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 Portal Server software you should perform the following tasks:
Verify Current Version Information
You can verify the current version of Portal Server using the following command:
PortalServer7-base/bin/psadmin --version --adminuser admin_ID
-f adminpasswordfile.
Table 15-5 Portal Server Version Verification Outputs
Java ES Release
Portal Server Version Number
Release 2
6.3
Release 3
6.3.1
Release 4
6.3.11
IFR Release
7.0
Release 5
7.1
Release 5U1
7.1U2
1The only difference between Release 3 and Release 4 is a patch. You can check for the Release 4 patches using the Solaris showrev -p | grep patch_ID command and the Linux rpm -qa sun-portal-core command and comparing the versions to those listed in the Java ES Release 4 Upgrade Guide.
Upgrade Portal Server 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 Portal Server has no hard upgrade dependencies. Upgrade of shared components is therefore optional.
Back Up Release 5 Portal Server Configuration Information
Upgrade of Portal Server to Release 5U1 does not require the reconfiguration of Portal Server software. Therefore backup of configuration information is optional.
Obtain Required Configuration Information and Passwords
Depending on the web container upgrade scenario (see Table 15-4), the psupdate script requires you to input information about passwords and other web container configuration data. The information required for different web container upgrade scenarios is shown in Table 15-6. Be sure to assemble the relevant information before beginning the Portal Server upgrade.
Table 15-6 Information Required by psupdate Script per Web Container Upgrade Scenario
Information
Upgrade Scenario1
Web Server 7.x Example Values:
Scenario 2Application Server 8.x Example Values:
Scenario 53Portal Server Configuration Directory
PortalServer7Config-base
PortalServer7Config-base
Web Container Admin Hostname
2 and 5
localhost
localhost
Web Container Admin Port
2 and 5
8989
4848
Web Container Admin Protocol
2 and 5
https
https
Web Container Admin User ID
2 and 5
admin
admin
Web Container Admin Password
2 through 5
Web Container Master Password
3 through 5
N/A
Directory Manager (cn=Directory manager) Password
1 through 5
Access Manager LDAP User Password
(Directory Server ldapuser Password)1 through 5
LDAP (Directory Server) Host
1 through 5
LDAP (Directory Server) Port
1 through 5
LDAP (Directory Server) Root Suffix
1 through 5
LDAP (Directory Server) Bind DN
1 through 5
1Web Container Upgrade Scenario #5 applies to upgrading Portal Server from Release 2.
Upgrading Release 5 Portal Server (Solaris)
This section discusses considerations that impact the upgrade procedure for Portal Server, followed by a description of the procedure itself.
Upgrade Considerations (Solaris)
The upgrade of Portal Server software to Java ES Release 5U1 takes into account the following considerations:
- In a deployment architecture in which there are multiple instances of Portal Server running on a single computer (all corresponding to the same installed Portal Server image), you only have to upgrade the Portal Server image once.
- Portal Server software consists of subcomponents that perform a number of different roles, but are all upgraded together:
- Portal-base. Includes administrative Mbeans and accompanying administrative software, Logging Framework, and monitoring-related software, all of which are packaged together.
- Portal Server web applications. Consists of a number of web applications that are deployed in a web container. At least some of these web applications require support from Access Manager and, in turn, Directory Server.
- Secure Remote Access core. Software that supports Portal Server Secure Remote Access: some servlets and applets embedded in jar files and some supporting files that cannot be deployed in a web container.
- The Release 5U1 Portal Server upgrade patches for Solaris OS are shown in the following table:
Table 15-7 Patches1 to Upgrade Portal Server to Release 5U1 on Solaris
Description
Patch ID: SPARC
Solaris 9 & 10
Patch ID: X86
Solaris 9 & 10
Portal Server core
124301-07
124302-07
Portal Server localization
(If Release 5 Portal Server had been freshly installed or upgraded from Release 2, 3, or 4 Portal Server)125301-04
125301-04
Portal Server localization
(If Release 5 Portal Server had been upgraded from Portal Server IFR 7.0)123254-04
124590-04
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.
- The psupdate script, needed to complete the upgrade of Portal Server and to update sample portlet applications, requests you to input additional information (see Table 15-6).
Upgrade Procedure (Solaris)
The procedure documented below applies to Portal Server instances residing locally on the computer where the upgrade is taking place.
PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile --name sraProfileName --type gatewayPortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile --name sraProfileName --type nlproxyPortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile --name sraProfileName --type rwproxyCheck that the processes have stopped:
Gateway: netstat -an | grep 443
Rewriter Proxy: netstat -an | grep 10443
Netlet Proxy: netstat -an | grep 10555
- Obtain the latest Portal Server upgrade patches, based on Table 15-7.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the appropriate Portal Server core and, if needed, localization patches in Table 15-7, 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 4.
- Restart Common Agent Container, if it has not been upgraded to Release 5U1 and restarted as part of that upgrade.
rel5CAC-admin-dir/bin/cacaoadm stop
rel5CAC-admin-dir/bin/cacaoadm start- Restart the web container.
- Stop the web container as follows:
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopWeb Server 7.0:
Instance Server--
WebServer7Config-base/https-configName/bin/stopserv
Admin Server--
WebServer7Config-base/admin-server/bin/stopservApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Start the web container as follows:
Web Server 6.x:
Admin Server--
WebServer6-base/https-adminserver/start
Instance Server--
WebServer6-base/https-instanceName/startWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/startserv
Instance Server--
WebServer7Config-base/https-configName/bin/startservApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Run the psupdate script.
cd PortalServer7-base/bin
./psupdate -aIf the psupdate command fails on the Solaris 10 platform, modify the value of LD_LIBRARY_PATH to remove /usr/lib (or prepend /usr/lib/mps/sasl2) and then run the psupdate script again.
The script requests you to input additional information (see Table 15-6) needed to upgrade Portal Server and update sample portlet applications.
Note
Be sure you enter correct values for psupdate parameters, as you can't go back and change them, and it is also very difficult to roll back changes made by the psupdate script.
- Restart Common Agent Container.
Use the commands in Step 6.
- Restart the web container.
Use the commands in Step 7.
Upgrading Release 5 Portal Server (Linux)
This section discusses considerations that impact the upgrade procedure for Portal Server, followed by a description of the procedure itself.
Upgrade Considerations (Linux)
The upgrade of Portal Server 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 Portal Server upgrade patches for Linux OS are shown in the following table:
Table 15-8 Patches1 to Upgrade Portal Server on Linux
Description
Patch ID and RPM names
Portal Server core
124303-07
- sun-portal-admin-7.1-2.07.i386.rpm
- sun-portal-base-7.1-2.07.i386.rpm
- sun-portal-portlets-7.1-2.07.i386.rpm
- sun-portal-search-7.1-2.07.i386.rpm
- sun-portal-sracommon-7.1-2.07.i386.rpm
- sun-portal-sracore-7.1-2.07.i386.rpm
- sun-portal-sragateway-7.1-2.07.i386.rpm
- sun-portal-sranetletproxy-7.1-2.07.i386.rpm
- sun-portal-srarewriterproxy-7.1-2.07.i386.rpm
Portal Server localization
125302-04
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 Portal Server instances residing locally on the computer where the upgrade is taking place.
Caution
An upgrade from Release 5 to Release 5U1 on Linux cannot be rolled back. Make sure you back up your system before performing the following procedure.
PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile --name sraProfileName --type gatewayPortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile --name sraProfileName --type nlproxyPortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile --name sraProfileName --type rwproxyCheck that the processes have stopped:
Gateway: netstat -an | grep 443
Rewriter Proxy: netstat -an | grep 10443
Netlet Proxy: netstat -an | grep 10555
- Obtain the latest Portal Server upgrade patches, based on Table 15-8.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the core and, if needed, localization patch for Portal Server, in that order.
For the core patch:
cd /workingDirectory/patch_ID
./updateThe update script installs the RPM's.
For the localization patch, install each RPM using the following command:
rpm -Fvh patchName-version.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-portal
The new version numbers of the RPMs should be returned.
- Restart Common Agent Container, if it has not been upgraded to Release 5U1 and restarted as part of that upgrade.
rel5CAC-admin-dir/bin/cacaoadm stop
rel5CAC-admin-dir/bin/cacaoadm start- Restart the web container.
- Stop the web container as follows:
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopWeb Server 7.0:
Instance Server--
WebServer7Config-base/https-configName/bin/stopserv
Admin Server--
WebServer7Config-base/admin-server/bin/stopservApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Start the web container as follows:
Web Server 6.x:
Admin Server--
WebServer6-base/https-adminserver/start
Instance Server--
WebServer6-base/https-instanceName/startWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/startserv
Instance Server--
WebServer7Config-base/https-configName/bin/startservApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Run the psupdate script.
cd PortalServer7-base/bin
./psupdate -aThe script requests you to input additional information (see Table 15-6) needed to upgrade Portal Server and update sample portlet applications.
Note
Be sure you enter correct values for psupdate parameters, as you can't go back and change them, and it is also very difficult to roll back changes made by the psupdate script.
- Restart Common Agent Container.
rel5CAC-admin-dir/bin/cacaoadm stop
rel5CAC-admin-dir/bin/cacaoadm start- Restart the web container.
Use the commands in Step 7.
Verifying the Upgrade
You can verify the upgrade of Portal Server to Release 5U1 using the following command:
See Table 15-5 for output values.
Post-Upgrade Tasks
There are no post-upgrade tasks beyond the steps described in Upgrade Procedure (Solaris) and Upgrade Procedure (Linux).
Rolling Back the Upgrade (Solaris)
This section describes the Release 5U1 upgrade rollback procedure for Portal Server on the Solaris platform.
- Log in as root or become superuser.
su -
- Remove the appropriate Portal Server core and, if needed, localization patches in Table 15-7, in that order.
patchrm patch_ID
- Restart the web container.
- Stop the web container as follows:
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/stopserv
Instance Server--
WebServer7Config-base/https-configName/bin/stopservApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Start the web container as follows:
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/start
Admin Server--
WebServer6-base/https-adminserver/startWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/startserv
Instance Server--
WebServer7Config-base/https-configName/bin/startservApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Run the psupdate script for the appropriate Portal Server core patch.
cd PortalServer7Data-base/psupdate.patch_ID
./psupdate -rIf the psupdate command fails on the Solaris 10 platform, modify the value of LD_LIBRARY_PATH to remove /usr/lib (or prepend /usr/lib/mps/sasl2) and then run the psupdate script again.
- Restart Common Agent Container.
rel5CAC-admin-dir/bin/cacaoadm start
- Restart the web container.
Use the commands in Step 3.
Rolling Back the Upgrade (Linux)
Rollback of the Release 5 to Release 5U1 upgrade is not supported.
Multiple Instance Upgrades
In some deployment architectures Portal Server is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Portal Server instances running on multiple computers with a load balancer to distribute the load.
In the case of load-balanced instances of Portal Server, you can perform a rolling upgrade in which you upgrade the Portal Server instances sequentially without interrupting service. The rolling upgrade is achieved by disabling a Portal Server instance in the load balancer, performing the upgrade as described in Release 5 Portal Server Upgrade, and then enabling the instance in the load balancer. Perform this procedure for each Portal Server instance.
Upgrading Portal Server from Java ES Release 4This section includes information about upgrading Portal Server 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 Portal Server to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is performed using an upgrade script, psupgrade. The script installs new packages, migrates configuration data when necessary, updates localization files, and re-deploys Portal Server web applications to the web container.
- Upgrade Dependencies. Portal Server has dependencies on a number of Java ES shared components (see Table 1-10). While Release 5U1 Portal Server is compatible with the Release 4 version of these shared components, upgrade of shared components is nevertheless necessary because the psupgrade script used to upgrade Portal Server requires the Release 5U1 version of the ANT shared component.
Release 5U1 Portal Server also has dependencies upon a web container, Access Manager, and Directory Server, as described in Portal Server Dependencies. Two approaches to upgrading these dependencies are supported (see Selective Upgrade Issues):
- Backward Compatibility. Release 5U1 Portal Server is not backwardly compatible with the Release 4 version.
- Upgrade Rollback. Rollback of the Release 5U1 upgrade of Portal Server to Release 4 consists of restoring Release 4 packages, restoring Release 4 Directory data, and redeploying Portal Server web applications to the web container.
- Platform Issues. The general approach for upgrading Portal Server is the same on both Solaris and Linux operating systems, however Release 5U1 Portal Server is installed in a new path on Solaris OS, but in the same Release 4 path on Linux OS.
Release 4 Portal Server Upgrade
This section describes how to perform an upgrade of Release 4 Portal Server 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:
Release 4 Pre-Upgrade Tasks
Before you upgrade Portal Server, you should perform the following tasks:
Verify Current Version Information
You can verify the current version of Portal Server using the following command:
See Table 15-5 for output values.
Upgrade Portal Server Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1.
While Release 5U1 Portal Server is compatible with the Release 4 version of Java ES shared components, upgrade of shared components is nevertheless necessary because the psupgrade script used to upgrade Portal Server requires the Release 5U1 version of the ANT shared component.
If you choose to upgrade any of the Portal Server product component dependencies to Release 5U1, they all need to be upgraded (see Selective Upgrade Issues). The dependencies should be upgraded in the order below (skipping any that might already have been upgraded), before you upgrade Portal Server.
- Shared Components. Instructions for synchronizing Java ES shared components to Release 5U1 are provided in Upgrading Java ES Shared Components.
- Directory Server. Instructions for upgrading Directory Server to Release 5U1 are provided in Chapter 5, "Directory Server".
- Web Container Software. Instructions for upgrading Web Server or Application Server are provided in Chapter 7, "Web Server" and Chapter 11, "Application Server", respectively.
- Access Manager (Access Manager SDK). Instructions for upgrading Access Manager to Release 5U1 are provided in Chapter 14, "Access Manager".
- Portal Server Secure Remote Access. Instructions for upgrading Portal Server Secure Remote Access to Release 5U1 are provided in Chapter 16, "Portal Server Secure Remote Access".
- Java DB. Instructions for upgrading Java DB to Release 5U1 are provided in Chapter 8, "Java DB".
- Service Registry. Instructions for upgrading Service Registry to Release 5U1 are provided in Chapter 12, "Service Registry".
- Communications Express. Instructions for upgrading Communications Express to Release 5U1 are provided in the Sun Java Communications Suite Upgrade Guide, http://docs.sun.com/doc/819-7561.
Obtain Required Configuration Information and Passwords
Depending on the web container upgrade scenario (see Table 15-4), the psupgrade script requires you to input information about passwords and other web container configuration data. The information required for different web container upgrade scenarios is shown in Table 15-9. Be sure to assemble the relevant information before beginning the Portal Server upgrade.
Table 15-9 Information Required by psupgrade Script per Web Container Upgrade Scenario
Information
Upgrade Scenario1
Web Server 7.x Example Values:
Scenario 2Application Server 8.x Example Values:
Scenario 53Upgrade Portal Server on Web Server 7.0 (yes/no)
2
Yes
N/A
Web Container Install Directory
2 and 5
WebServer7-base
AppServer8Install-base
Web Container Virtual Server Instance Name
2
https-configName2
N/A
Web Container Instance Name
5
N/A
server1
Web Container Instance Directory
2
WebServer7Config-base/
https-configName4/N/A
Portal Instance Deploy Directory
5
N/A
AppServer8Config-base/
domains/domainNameWeb Container Instance Port
2 and 5
80
80
Web Container Instance Protocol
2 and 5
http
http
Web Container Config Name
2
configName4
N/A
Web Container Domain Name
5
N/A
domain1
Web Container Docs Root Directory
2 and 5
WebServer7Config-base/
https-configName4/docs/AppServer8Config-base/
domains/domainName/
docrootWeb Container Admin Hostname
2 and 5
localhost
localhost
Web Container Admin Port
2 and 5
8989
4849
Web Container Admin Protocol
2 and 5
https
https
Web Container Admin User ID
2 and 5
admin
admin
Web Container Admin Password
2 through 5
Web Container Master Password
3 through 5
N/A
Directory Manager (cn=Directory manager) Password
1 through 5
SRA Log User Password3
1 through 5
Access Manager Admin Password
1 through 5
Directory Server ldapuser Password
1 through 5
Portal Instance ID4
1 through 5
1Web Container Upgrade Scenario #5 applies to upgrading Portal Server from Release 2.
2The default value of configName is hostName.domainName.
3This information is needed to configure Portal Server Secure Remote Access components when installed with Portal Server.
4A unique, non-null, value must be provided for this parameter. Values must be alpha numeric, and can include a hyphen (-).
Back Up Release 4 Portal Server Data
Upgrade of Portal Server to Release 5U1 does not require the reconfiguration of Portal Server software. However, as a safety measure the psupgrade script will back up the following directories where configuration information is stored:
Remove Configuration for Load Balancer
In cases in which Portal Server instances are accessed through a load balancer, the value of the LOAD_BALANCER_URL property used to configure such access can interfere with Portal Server upgrade. This setting must therefore be modified before performing the upgrade. To modify the LOAD_BALANCER_URL property setting:
- Note which of the following configuration files are locally resident (some of which support Portal Server Secure Remote Access components that might be locally installed):
PortalServer6Config-base/PSConfig.properties
PortalServer6Config-base/GWConfig.properties (if Gateway is local)
PortalServer6Config-base/RWPConfig.properties (if Rewriter Proxy is local)
PortalServer6Config-base/NLPConfig.properties (if Netlet Proxy is local)- Record the current value of the LOAD_BALANCER_URL property in these configuration files.
- Modify the value of the LOAD_BALANCER_URL property to point to the relevant Portal Server instance:
LOAD_BALANCER_URL=portalHostName:port/portal
Remove Configuration for Directory Proxy Server
In cases in which Portal Server instances access Directory Server through a Directory Proxy Server instance, the Directory Proxy Server host and port number settings must be modified before performing the upgrade and then restored to their original values after upgrade is complete.
To modify the appropriate settings:
- Record the current value of the com.iplanet.am.directory.host and com.iplanet.am.directory.port properties in the following Access Manager configuration file:
AccessManagerConfig-base/config/AMConfig.properties
- Modify the values of these properties to point directly to the relevant Directory Server instance.
Upgrading Release 4 Portal Server (Solaris)
This section discusses considerations that impact the upgrade procedure for Portal Server followed by a description of the procedure itself.
Upgrade Considerations (Solaris)
The upgrade of Portal Server software to Release 5U1 takes into account the following considerations:
- All Portal Server instances corresponding to the same installed Portal Server image are upgraded at the same time.
- Portal Server software consists of subcomponents that perform a number of different roles, but are all upgraded together:
- Portal-base. Includes administrative Mbeans and accompanying administrative software, Logging Framework, and monitoring-related software, all of which are packaged together.
- Portal Server web applications. Consists of a number of web applications that are deployed in a web container. At least some of these web applications require support from Access Manager and, in turn, Directory Server.
- Secure Remote Access core. Software that supports Portal Server Secure Remote Access: some servlets and applets embedded in jar files and some supporting files that cannot be deployed in a web container.
- The psupgrade script automatically detects which Portal Server subcomponents and which web container dependencies are installed on the host computer. For example, the script queries the system to detect the version of Application Server or Web Server to which you are deploying Portal Server web applications, and tailors the information it requests depending on the information it can detect.
Upgrade Procedure (Solaris)
The procedure documented below applies to Portal Server on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- If you have not already done so, synchronize all shared components to Release 5U1.
Instructions are provided in Chapter 2, "Upgrading Java ES Shared Components".
This step is a necessary prerequisite to running the psupgrade script in Step 8.
- Stop any instances of the Portal Server Secure Remote Access Gateway, Rewriter Proxy, or Netlet Proxy that might be running locally.
PortalServer6-base/bin/gateway stop
PortalServer6-base/bin/netletd stop
PortalServer6-base/bin/rwproxyd stopCheck that the processes have stopped:
Gateway: netstat -an | grep 443
Rewriter Proxy: netstat -an | grep 10443
Netlet Proxy: netstat -an | grep 10555- Make sure Access Manager is running if it is deployed to a web container different from the one to which Portal Server is deployed.
- If not already running, start Portal Server by starting the web container to which it is deployed.
Web Server 6.x:
Admin Server--
WebServer6-base/https-adminserver/start
Instance Server--
WebServer6-base/https-instanceName/startWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/startserv
Instance Server--
WebServer7Config-base/https-configName/bin/startservApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Set two environment variables (ANT_HOME and JAVA_HOME) needed by the psupgrade script. For example,
export ANT_HOME=/usr/sfw
export JAVA_HOME=/usr/jdk/entsys-j2se- Make sure you have adequate swap space on your computer.
As a guideline, the swap space should be set to twice the amount of physical ram.
- Run the psupgrade script from the Java ES 5 Update 1 distribution.
cd os_arch/Products/portal_svr/Tools/upgrade/bin
./psupgradewhere os_arch matches your platform, such as Solaris_sparc.
The psupgrade script detects installed Portal Server components and localization packages, invokes the Java ES installer to install new packages, and queries the system to detect the location and port number and other information regarding the web container to which you are deploying Portal Server web applications. Depending on web container upgrade scenario (see Table 15-4), the script requests you to input additional information required to deploy Portal Server to the appropriate web container.
Table 15-9 shows the information requested for the different web container upgrade scenarios in Table 15-4.
- Stop and restart the web container.
While not required in all situations, restarting the web container ensures that Portal Server starts in a clean state.
- Stop the web container as follows:
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopWeb Server 7.0:
Instance Server--
WebServer7Config-base/https-configName/bin/stopserv
Admin Server--
WebServer7Config-base/admin-server/bin/stopservApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Start the web container using the commands in Step 5.
- Apply the latest Portal Server maintenance patches, if any.
Use the procedure documented in Upgrading Release 5 Portal Server (Solaris), except apply the procedure to upgrading from Release 5U1 instead of from Release 5.
Upgrading Release 4 Portal Server (Linux)
This section discusses considerations that impact the upgrade procedure for Portal Server followed by a description of the procedure itself.
Upgrade Considerations (Linux)
The upgrade of Portal Server software to Release 5U1 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that Release 5U1 Portal Server is installed in the same path as Release 4 on Linux OS. As a result, the psupgrade script removes the previous RPMs when installing the Release 5U1 RPMs.
Upgrade Procedure (Linux)
The procedure documented below applies to Portal Server on the computer where the upgrade is taking place.
Caution
An upgrade from Release 4 to Release 5U1 on Linux cannot be rolled back. Make sure you back up your system before performing the following procedure.
- Log in as root or become superuser.
su -
- If you have not already done so, synchronize all shared components to Release 5U1.
Instructions are provided in Chapter 2, "Upgrading Java ES Shared Components".
This step is a necessary prerequisite to running the psupgrade script in Step 8.
- Stop any instances of the Portal Server Secure Remote Access Gateway, Rewriter Proxy, or Netlet Proxy that might be running locally.
PortalServer6-base/bin/gateway stop
PortalServer6-base/bin/netletd stop
PortalServer6-base/bin/rwproxyd stopCheck that the processes have stopped:
Gateway: netstat -an | grep 443
Rewriter Proxy: netstat -an | grep 10443
Netlet Proxy: netstat -an | grep 10555- Make sure Access Manager is running if it is deployed to a web container different from the one to which Portal Server is deployed.
- If not already running, start Portal Server by starting the web container to which it is deployed.
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/start
Admin Server--
WebServer6-base/https-adminserver/startWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/startserv
Instance Server--
WebServer7Config-base/https-configName/bin/startservApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Set two environment variables (ANT_HOME and JAVA_HOME) needed by the psupgrade script. For example,
export ANT_HOME=/opt/sun
export JAVA_HOME=/usr/jdk/entsys-j2se- Make sure you have adequate swap space on your computer.
As a guideline, the swap space should be set to twice the amount of physical ram.
- Run the psupgrade script from the Java ES 5 Update 1 distribution.
cd os_arch/Products/portal_svr/Tools/upgrade/bin
./psupgradewhere os_arch matches your platform, such as Linux_x86.
The psupgrade script detects installed Portal Server components and localization packages, invokes the Java ES installer to install new packages, and queries the system to detect the location and port number and other information regarding the web container to which you are deploying Portal Server web applications. Depending on web container upgrade scenario (see Table 15-4), the script requests you to input additional information required to deploy Portal Server to the appropriate web container.
Table 15-9 shows the information requested for the different web container upgrade scenarios in Table 15-4.
- Stop and restart the web container.
While not required in all situations, restarting the web container ensures that Portal Server starts in a clean state.
- Stop the web container as follows:
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/stopserv
Instance Server--
WebServer7Config-base/https-configName/bin/stopservApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Restart the web container using the commands in Step 5.
- Apply the latest Portal Server maintenance patches, if any.
Use the procedure documented in Upgrading Release 5 Portal Server (Solaris), except apply the procedure to upgrading from Release 5U1 instead of from Release 5.
Verifying the Upgrade
You can verify the installation of Release 5U1 packages using the following command:
See Table 15-5 for output values.
To verify the full upgrade, confirm that the Portal Desktop comes up and the psadmin administration utility functions as documented.
You can also check the following upgrade log files:
/var/sadm/install/logs/Sun_Java_System_Portal_Server_upgrade.0.0.log*
PortalServer7Data-base/logs/admin/
PortalServer7Data-base/logs/config/Release 4 Post-Upgrade Tasks
Please note the post-upgrade procedures required to address the following situations:
Migrate Custom web-src Data
If you have added custom data, such as images, javascript files or any other files for constructing portal.war to the following directory:
PortalServer6-base/web-src
you have to copy these additional files to the corresponding directory in Release 5U1 Portal Server:
PortalServer7-base/web-src
Redeploy Custom Portlet Applications
If you have created and deployed custom portlet applications, then these portlets must be manually redeployed after upgrade to Release 5U1 Portal Server. Even though display profile entries will exist and the channel name will be displayed, content will not be seen until you redeploy your custom portlets.
Redeploy portlets using the following command:
PortalServer7-base/bin/psadmin deploy-portlet
You can confirm redeployment by looking for the corresponding .war and XML files in the following location:
PortalServer7Data-base/portals/Upgraded/war
Restore Configuration for Directory Proxy Server
If Portal Server instances have accessed Directory Server through a Directory Proxy Server instance, the Directory Proxy Server host and port number settings must be restored to their original values before upgrade. See Remove Configuration for Directory Proxy Server, in which the values of these properties was modified in preparation for upgrade.
Change in Logout Page
The Release 5U1 Portal Server logout page has been changed from the previous Access Manager logout page. Please note that this change does not represent a defect in the software.
Rolling Back the Upgrade (Solaris)
This section describes considerations that impact the upgrade rollback procedure for Portal Server followed by the procedure itself.
Rollback Considerations (Solaris)
The procedure for rolling back the upgrade to Release 5U1 consists of reverting back to the Release 4 installation at PortalServer6-base and redeploying the Release 4 web applications.
Rollback Procedure (Solaris)
- Log in as root or become superuser.
su -
- If Access Manager has been upgraded to Release 5U1, roll back Access Manager to Release 4.
The rollback of Portal Server to Release 4 will not succeed if Access Manager remains at Release 5U1.
- Restore Directory Server to the state it was in before upgrade.
Use the Directory Server backup/restore command line and GUI utilities. See the Directory Server Backup and Restore chapter of the Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide, http://docs.sun.com/doc/819-0995.
- Stop Portal Server by stopping its web container.
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopWeb Server 7.0:
Instance Server--
WebServer7Config-base/https-configName/bin/stopserv
Admin Server--
WebServer7Config-base/admin-server/bin/stopservApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Remove the Release 5U1 Portal Server packages.
- Restart Portal Server by starting its web container.
Web Server 6.x:
Admin Server--
WebServer6-base/https-adminserver/start
Instance Server--
WebServer6-base/https-instanceName/startWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/startserv
Instance Server--
WebServer7Config-base/https-configName/bin/startservApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Re-deploy the Release 4 Portal Server web applications using the following command from the Java ES 5 Update 1 distribution:
cd os_arch/Products/portal_svr/Tools/upgrade/bin
./psupgrade rollbackwhere os_arch matches your platform, such as Solaris_sparc.
The psupgrade rollback command un-deploys Release 5U1 Portal Server web applications and re-deploys Release 4 Portal Server web applications.
The command redeploys content from PortalServer6-base/web-src to /var/PortalServer6-base/https-hostName/deploy-dir/web-apps. Any customizations to the Portal Server web application should therefore be first made to /web-src and then deployed to /web-apps. Any changes you might make under /web-apps should be replicated in /web-src before running the psupgrade rollback command, or such changes will be overwritten.
- Stop and restart the web container.
While not required in all situations, restarting the web container ensures that Portal Server starts in a clean state.
Rolling Back the Upgrade (Linux)
Because the upgrade to Release 5U1 requires the removal of the Release 4 binaries, it is very difficult to roll back the upgrade on Linux.
One approach to rollback would be to create a parallel system before upgrading and testing that system before attempting an upgrade. If you need to roll back the upgrade, you can revert back to that parallel system.
Multiple Instance Upgrades
In some deployment architectures Portal Server is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Portal Server instances running on multiple computers with a load balancer to distribute the load.
In the case of load-balanced instances of Portal Server, you can perform a rolling upgrade in which you upgrade the Portal Server instances sequentially without interrupting service, as described below. The procedure takes into account the following constraint: Release 4 Portal Server does not work with Release 5U1 Portal Server directory data.
The deployment architecture shown in Figure 15-1 will be used to illustrate the procedure for a rolling upgrade of Release 4 Portal Server instances to Release 5U1.
Note
For architectures that include Portal Server Secure Remote Access components, see Multiple Instance Upgrades.
In the architecture of Figure 15-1, multiple Portal Server instances are accessed by way of a load balancer to provide for availability and scalability. The Portal Server instances, in turn, access Access Manager instances through a load balancer. The The Access Manager and Access Manager SDK instances access a directory that is set up for multi-master replication (MMR). While other Directory Server replication schemes are possible, MMR is representative of highly available and scalable directory services.
In Figure 15-1, the multiple instances of Portal Server, Access Manager, and Directory Server are grouped to facilitate explanation of the upgrade procedure. Portal Server 2, for example, is representative of the second through nth instances of Portal Server.
Figure 15-1 Example Deployment Architecture for Multiple Portal Server Instances
Rolling upgrade of Release 4 Portal Server to Release 5U1 is performed as follows:
- If you are upgrading Release 4 Access Manager to Release 5U1, perform a rolling upgrade as documented in Multiple Instance Upgrades. Note that in upgrading Release 4 Portal Server to Release 5U1, you are not required to upgrade Release 4 Access Manager to Release 5U1.
- Configure Portal Server 2 to point to Directory Server 2 rather than Directory Server 1.
For brevity, in this and succeeding steps, "Portal Server 2" will mean Portal Server 2 through Portal Server n.
- Upgrade Portal Server 1.
- Disable Portal Server 1 in Load Balancer B.
Requests will no longer be routed to Portal Server 1.
- Disable Directory Server MMR.
Directory Server 2 will no longer by synchronized with Directory Server 1.
- Upgrade Access Manager SDK 1B to Release 5U1.
Use the procedure in Release 4 Access Manager SDK-only Upgrades.
- Upgrade Portal Server 1 to Release 5U1.
Perform the upgrade of the Portal Server instance as described in Release 4 Portal Server Upgrade, noting the following:
- Make special note of the following pre-upgrade task: Remove Configuration for Load Balancer.
- Confirm, before performing the upgrade, that the value of am.encryption.pwd in the AccessManagerConfig-base/config/AMConfig.properties file is the same for the local Access Manager SDK as for its associated remote Access Manager instance.
- Make sure that you provide a non-null, unique value for the Portal Instance ID parameter requested by psupgrade for each Portal Server instance that you are upgrading.
Portal Server data for Directory Server 1 is updated to Release 5U1.
- Enable Portal Server 1 in Load Balancer B.
Requests will be once again routed to Portal Server 1.
- Upgrade Portal Server 2.
- Disable Portal Server 2 in Load Balancer B.
Requests will no longer be routed to Portal Server 2.
- Restore the configuration of Portal Server 2 to point to Directory Server 1.
- Upgrade Access Manager SDK 2B to Release 5U1.
Use the same procedure as in Step c.
- Upgrade Portal Server 2 to Release 5U1.
Use the same procedure as in Step d.
- Enable Portal Server 2 in Load Balancer B.
Requests will be once again routed to Portal Server 2.
- Enable Directory Server MMR.
The Portal Server data for Directory Server 2, is now synchronized with Directory Server 1.
Upgrading Portal Server from Java ES Release 3The procedure for upgrading Java ES 2005Q1 (Release 3) Portal Server to Release 5U1 is the same as that for upgrading Release 4 Portal Server to Release 5U1, with the following exceptions:
Release 3 Pre-Upgrade Task: Upgrading Portal Server Dependencies
However, when upgrading Portal Server from Release 3, you have to upgrade both Access Manager and web container (Web Server or Application Server) to Release 4 or to Release 5U1 before upgrading Portal Server, but you cannot leave any dependencies at Release 3, nor upgrade some dependencies to Release 4 and others to Release 5U1. For more information, see Selective Upgrade Issues.
The following dependencies need to be upgraded in the order shown below.
- Shared Components. Instructions for upgrading Java ES shared components to Release 5U1 are provided in Chapter 2, "Upgrading Java ES Shared Components".
- Directory Server. Instructions for upgrading Directory Server to Release 5U1 are provided in Chapter 5, "Directory Server".
- Web Container Software. Instructions for upgrading Web Server or Application Server are provided in Chapter 7, "Web Server" and Chapter 11, "Application Server", respectively.
- Access Manager (Access Manager SDK). Instructions for upgrading Access Manager to Release 5U1 are provided in Chapter 14, "Access Manager".
Upgrading Release 3 Portal Server
To upgrade Release 3 Portal Server to Release 5U1, use the instructions in Upgrading Portal Server from Java ES Release 4, except substitute Release 3 wherever Release 4 is referenced.
Release 3 Post-Upgrade Tasks
When upgrading Release 3 Portal Server to Release 5U1, you must perform, in addition to the post-upgrade procedures documented in Release 4 Post-Upgrade Tasks, the post-upgrade procedures required to address the following situations:
Subscribing a Discussion
Subscribing a discussion in a community will not succeed unless you first edit the global display profile top level properties to add the following String property:
helpURL=en/desktop/usedesk.htm
Use the following procedure:
- Create a display profile XML snippet file, helpUrl.xml:
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Properties>
<String name="helpURL" value="en/desktop/usedesk.htm" />
</Properties>- Run the Global display profile properties using the following command:
./psadmin modify-dp -u amadminUser -f /tmp/passwordFile -p portal_ID
-m -g helpUrl.xmlwhere the -m option is required to not overwrite the entire Global display profile.
Multiple Instance Upgrades
In some deployment architectures Portal Server is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Portal Server instances running on multiple computers with a load balancer to distribute the load.
In the case of load-balanced instances of Portal Server, you can perform a rolling upgrade in which you upgrade the Portal Server instances sequentially without interrupting service, as described below. The procedure takes into account the following constraint: Release 3 Portal Server does not work with Release 5U1 Portal Server directory data.
To perform a rolling upgrade from Release 3 Portal Server to Release 5U1, use the same procedure documented in Multiple Instance Upgrades, except substitute Release 3 wherever Release 4 is referenced. In addition, you must also upgrade Access Manager, as described in Step 1.
Upgrading Portal Server from Java ES Release 2Direct upgrade of Java ES 2004Q2 (Release 2) Portal Server to Release 5U1 is not supported.
However you can perform this upgrade by first upgrading Release 2 Portal Server to Release 5 (as documented in the Java Enterprise System 5 Update 1 Upgrade Guide for UNIX, http://docs.sun.com/doc/819-6553) and then upgrading Release 5 Portal Server to Release 5U1 (as documented in Upgrading Portal Server from Java ES 5).
Upgrading Portal Server from the Interim Feature Release 7.0This section includes information about upgrading Portal Server from the Interim Feature Release (IFR) 7.0 2005Q4 to Java ES 5 Update 1 (Release 5U1).
The section covers the following topics:
Portal Server IFR Upgrade Introduction
When upgrading Portal Server IFR 7.0 to Release 5U1 Portal Server, consider the following aspects of the upgrade process:
- The Portal Server IFR is not supported on Application Server 7.x, hence Upgrade Scenario 5 in Table 15-4 does not apply.
- The upgrade of Portal Server IFR 7.0 to Release 5U1 Portal Server involves the application of two sets of patches (a Portal Server 7.1 patch and a Release 5U1 patch) and running of two scripts (psupgrade and psupdate).
- The psupgrade script, used for upgrading Portal Server IFR to Release 5U1, does not install new packages, as in the case of upgrade from Release 4. Instead, the upgrade procedure will require you to apply the following Portal Server 7.1 patches:
Table 15-10 Patches1 to Upgrade Portal Server IFR to Release 5U1
Description
Patch ID: Solaris 9 & 10
Patch ID: Linux
Portal Server 7.1 core
121465-28 (SPARC)
121466-28 (x86)
121467-28
Portal Server 7.1
localization123254-04 (SPARC)
124590-04 (x86)
125302-04
1Patch revision numbers are the minimum required for upgrade to Java ES Release 5U1. If newer revisions become available, use the newer ones instead of those shown in the table.
Portal Server IFR 7.0 Upgrade
This section describes how to perform an upgrade of Portal Server from the IFR 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:
IFR 7 Pre-Upgrade Tasks
Pre-upgrade tasks for the IFR upgrade are the same as for the Release 4 upgrade (see Release 4 Pre-Upgrade Tasks), with the following exception:
Information is requested by both the psupgrade and psupdate scripts that are used in upgrading from Portal Server IFR:
- The information required by the psupgrade script, as detailed in Obtain Required Configuration Information and Passwords, does not fully apply to upgrade from Portal Server IFR. Because Portal Server IFR is not supported on Application Server 7.x, web container upgrade Scenario 5 in Table 15-9 is not applicable.
- The information required by the psupdate script is detailed in Obtain Required Configuration Information and Passwords
Upgrading Portal Server IFR 7.0 (Solaris)
This section discusses considerations that impact the upgrade procedure for Portal Server IFR followed by a description of the procedure itself.
IFR 7 Upgrade Considerations (Solaris)
The Portal Server IFR upgrade to Release 5U1 takes into account the same considerations as the Release 4 upgrade (see Upgrade Considerations (Solaris)).
In addition, see the issues raised in Portal Server IFR Upgrade Introduction.
IFR 7 Upgrade Procedure (Solaris)
The procedure documented below applies to Portal Server on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- Stop any instances of the Portal Server Secure Remote Access Gateway, Rewriter Proxy, or Netlet Proxy that might be running locally.
PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile -t gateway -N gatewayProfileNamePortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile -t rwproxy -N gatewayProfileNamePortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile -t nlproxy -N gatewayProfileNameCheck that the processes have stopped:
Gateway: netstat -an | grep 443
Rewriter Proxy: netstat -an | grep 10443
Netlet Proxy: netstat -an | grep 10555- Make sure Access Manager is running if it is deployed to a web container different from the one to which Portal Server is deployed.
- If not already running, start Portal Server by starting the web container to which it is deployed.
Web Server 6.x:
Admin Server--
WebServer6-base/https-adminserver/start
Instance Server--
WebServer6-base/https-instanceName/startApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Apply the required Portal Server 7.1 patches.
- Obtain the required patches, based on Table 15-10.
Always use the latest patch revisions available, unless directed to use a specific revision.
Patches can be downloaded to /workingDirectory from: http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access
- Apply the appropriate Portal Server patch and, if needed, localization patch.
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 b.
- Apply the required Release 5U1 patch.
- Obtain the required patch, based on Table 15-7.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the appropriate Portal Server patch and, if needed, localization patch in Table 15-10.
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 b.
- Set two environment variables (ANT_HOME and JAVA_HOME) needed by the psupgrade script:
export ANT_HOME=/usr/sfw
export JAVA_HOME=/usr/jdk/entsys-j2se- Make sure you have adequate swap space on your computer.
As a guideline, the swap space should be set to twice the amount of physical ram.
- Run the psupgrade script.
cd PortalServer7-base/bin
./psupgradeThe psupgrade script is not run from the Java ES 5 Update 1 distribution and does not invoke the Java ES installer (the packages were already patched).
The script queries the system to detect the location and port number and other information regarding the web container to which you are deploying Portal Server web applications. Depending on web container upgrade scenario (see Table 15-4), the script requests you to input additional information required to deploy Portal Server to the appropriate web container.
Table 15-9 shows the information requested for the different web container upgrade scenarios in Table 15-4.
Note
Be sure you enter correct values for psupgrade parameters, as you can't go back and change them, and it is also very difficult to roll back changes made by the psupgrade script.
- Restart the web container.
- Stop the web container as follows:
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Start the web container as follows:
Web Server 6.x:
Admin Server--
WebServer6-base/https-adminserver/start
Instance Server--
WebServer6-base/https-instanceName/startApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Run the psupdate script.
cd PortalServer7-base/bin
./psupdate -aIf the psupdate command fails on the Solaris 10 platform, modify the value of LD_LIBRARY_PATH to remove /usr/lib (or prepend /usr/lib/mps/sasl2) and then run the psupdate script again.
The script requests you to input additional information (see Table 15-6) needed to upgrade Portal Server and update sample portlet applications.
Note
Be sure you enter correct values for psupdate parameters, as you can't go back and change them, and it is also very difficult to roll back changes made by the psupdate script.
- Restart Common Agent Container, if it has not been upgraded to Release 5U1 and restarted as part of that upgrade.
rel5CAC-admin-dir/bin/cacaoadm stop
rel5CAC-admin-dir/bin/cacaoadm start- Restart the web container.
Use the commands in Step 10.
Upgrading IFR 7 Portal Server (Linux)
This section discusses considerations that impact the upgrade procedure for Portal Server followed by a description of the procedure itself.
IFR 7 Upgrade Considerations (Linux)
The upgrade of Portal Server IFR software to Release 5U1 on the Linux platform takes into account the same considerations as on the Solaris platform (see IFR 7 Upgrade Considerations (Solaris)), except that installing Linux patches removes the previous RPMs.
IFR 7 Upgrade Procedure (Linux)
The procedure documented below applies to Portal Server on the computer where the upgrade is taking place.
Caution
An upgrade from Portal Server IFR to Release 5U1 on Linux cannot be rolled back. Make sure you back up your system before performing the following procedure.
- Log in as root or become superuser.
su -
- Stop any instances of the Portal Server Secure Remote Access Gateway, Rewriter Proxy, or Netlet Proxy that might be running locally.
PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile -t gateway -N gatewayProfileNamePortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile -t rwproxy -N gatewayProfileNamePortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
-f passwordFile -t nlproxy -N gatewayProfileNameCheck that the processes have stopped:
Gateway: netstat -an | grep 443
Rewriter Proxy: netstat -an | grep 10443
Netlet Proxy: netstat -an | grep 10555- Make sure Access Manager is running if it is deployed to a web container different from the one to which Portal Server is deployed.
- If not already running, start Portal Server by starting the web container to which it is deployed.
Web Server 6.x:
Admin Server--
WebServer6-base/https-adminserver/start
Instance Server--
WebServer6-base/https-instanceName/startApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Apply the required Portal Server 7.1 patches.
- Obtain the required patches, based on Table 15-10.
Always use the latest patch revisions available, unless directed to use a specific revision.
Patches can be downloaded to /workingDirectory from: http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access
- Apply the Portal Server core and, if needed, localization RPMs for Portal Server, in that order.
See the Readme file for the Portal Server patch, which describes how to use a script to apply the patch's RPMs:
cd /workingDirectory
where /workingDirectory is the directory to which you download the patch.
./upgradeportalrpm
The update script installs the RPM's.
For the localization patch, install each RPM using the following command:
rpm -Fvh patchName-version.rpm
Be sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrade was successful:
rpm -qa | grep sun-portal
The upgrade revision numbers of the RPMs should be returned.
- Apply the required Release 5U1 patch.
- Obtain the latest Portal Server upgrade patches, based on Table 15-8.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the core and, if needed, localization patch for Portal Server in Table 15-8, in that order.
cd /workingDirectory/patch_ID
./update- Confirm that the patch upgrades were successful.
rpm -qa | grep sun-portal
The new version numbers of the RPMs should be returned.
- Set two environment variables (ANT_HOME and JAVA_HOME) needed by the psupgrade script:
export ANT_HOME=/opt/sun
export JAVA_HOME=/usr/jdk/entsys-j2se- Make sure you have adequate swap space on your computer.
As a guideline, the swap space should be set to twice the amount of physical ram.
- Run the psupgrade script.
cd PortalServer7-base/bin
./psupgradeThe psupgrade script is not run from the Java ES 5 Update 1 distribution and does not invoke the Java ES installer (the packages were already patched).
The script queries the system to detect the location and port number and other information regarding the web container to which you are deploying Portal Server web applications. Depending on web container upgrade scenario (see Table 15-4), the script requests you to input additional information required to deploy Portal Server to the appropriate web container.
Table 15-9 shows the information requested for the different web container upgrade scenarios in Table 15-4.
Note
Be sure you enter correct values for psupgrade parameters, as you can't go back and change them, and it is also very difficult to roll back changes made by the psupgrade script.
- Restart the web container.
- Stop the web container as follows:
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Start the web container as follows:
Web Server 6.x:
Admin Server--
WebServer6-base/https-adminserver/start
Instance Server--
WebServer6-base/https-instanceName/startApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Run the psupdate script.
cd PortalServer7-base/bin
./psupdate -aThe script requests you to input additional information (see Table 15-6) needed to upgrade Portal Server and update sample portlet applications.
Note
Be sure you enter correct values for psupdate parameters, as you can't go back and change them, and it is also very difficult to roll back changes made by the psupdate script.
- Restart Common Agent Container, if it has not been upgraded to Release 5U1 and restarted as part of that upgrade.
rel5CAC-admin-dir/bin/cacaoadm stop
rel5CAC-admin-dir/bin/cacaoadm start- Restart the web container.
Use the commands in Step 10.
Verifying the Upgrade
You can verify the patching of Portal Server packages to Release 5U1 using the following command:
See Table 15-5 for output values.
To verify the full upgrade, confirm that the Portal Desktop comes up and the psadmin administration utility functions as documented.
You can also check the following upgrade log files at /var/sadm/install/logs:
IFR 7 Post-Upgrade Tasks
Please note the post-upgrade procedures required to address the following situations:
Portal Server Deployed in a Web Server Web Container
When upgrading Portal Server from IFR 7 to Release 5U1, and Portal Server is deployed in a Web Server web container that has been upgraded from Release 4 Web Server to Release 5U1 Web Server, you are not able to create a community using the Portal Server Console interface.
To address this problem, perform the following steps:
- Log in to the Release 5U1 Web Server administration console.
- Click on Configurations.
- Select the configuration for the Portal Server instance that is running.
- Click on the Java tab.
- View the Path settings for Class Path Prefix.
- Replace /opt/SUNWcacao/lib/cacao_cacao.jar
with /usr/lib/cacao/lib/cacao_caca0.jarPortal Server Deployed in an Application Server Web Container
When upgrading Portal Server from IFR 7 to Release 5U1, and Portal Server is deployed in an Application Server web container, portal applications can hang waiting to get Java DB connections.
To address this problem, perform the following steps:
- Remove settings in PortalServer7Data-base/derby/derby.properties for the following 2 parameters:
derby.drda.maxThreads
derby.drda.timeslice- Restart Java DB.
ANT_HOME/bin/ant
-DPS_CONFIG=PortalServer7Config-base/PSConfig.properties
-buildfile PortalServer7-base/lib/derby.xml
[stop-instance|start-instance]where ANT_HOME is /usr/sfw (on Solaris) and /opt/sun (on Linux).
- Change Java DB configuration settings for Application Server.
Using the Application Server Console, change attribute values for the following connection pool resources: communitymcPool, FileSharingDBPool, PointBasePool, SurveyDBPool.
Change the following attribute values as follows:
Idle Timeout to 300 or more
Resource Type to javax.sql.ConnectionPoolDataSource
Datasource classname to
org.apache.derby.jdbc.ClientConnectionPoolDataSource- Restart the Application Server instance in which Portal Server is deployed.
Rolling Back the Upgrade (Solaris)
This section describes considerations that impact the upgrade rollback procedure for Portal Server followed by the procedure itself.
Rollback Considerations (Solaris)
The procedure for rolling back the upgrade to Release 5U1 consists of reverting back to the IFR installation at PortalServer7-base and redeploying the IFR web applications.
Rollback Procedure (Solaris)
- Log in as root or become superuser.
su -
- Restore Directory Server to the state it was in before upgrade.
Use the Directory Server backup/restore command line and GUI utilities. See the Directory Server Backup and Restore chapter of the Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide, http://docs.sun.com/doc/819-0995.
- Stop Portal Server by stopping its web container.
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/stop
Admin Server--
WebServer6-base/https-adminserver/stopWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/stopserv
Instance Server--
WebServer7Config-base/https-configName/bin/stopservApplication Server 8.x:
AppServer8-base/bin/asadmin stop-domain --user admin_ID
--password password domainName- Remove the appropriate Release 5U1 core and, if needed, localization patches in Table 15-7, in that order.
patchrm patch_ID
- Restart Portal Server by starting its web container.
Web Server 6.x:
Instance Server--
WebServer6-base/https-instanceName/start
Admin Server--
WebServer6-base/https-adminserver/startWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/startserv
Instance Server--
WebServer7Config-base/https-configName/bin/startservApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Run the psupdate script for the appropriate Portal Server core patch.
cd PortalServer7Data-base/psupdate.patch_ID
./psupdate -rIf the psupdate command fails on the Solaris 10 platform, modify the value of LD_LIBRARY_PATH to remove /usr/lib (or prepend /usr/lib/mps/sasl2) and then run the psupdate script again.
- Restart the web container.
Use the commands in Step 3 and Step 5.
- Undeploy the Release 5U1 Portal Server web applications that were re-deployed during the upgrade to Release 5U1.
Use the web container's administration utilities (command line or console) to undeploy the following packages:
portal
psconsole
search1
wsssoportlet
guessnumber
portletsamples- Back out the Portal Server 7.1 patch in Table 15-10.
patchrm patch_ID
- Restart Portal Server by starting its web container.
Web Server 6.x:
WebServer-base/https-instanceName/startWeb Server 7.0:
Admin Server--
WebServer7Config-base/admin-server/bin/startserv
Instance Server--
WebServer7Config-base/https-configName/bin/startservApplication Server 8.x:
AppServer8-base/bin/asadmin start-domain --user admin_ID
--password password domainName- Deploy the Release 4 Portal Server web applications that were un-deployed during Step 8.
Use the web container's administration utilities (command line or console) to deploy the packages.
- Stop and restart the web container.
While not required in all situations, restarting the web container ensures that Portal Server starts in a clean state.
Rolling Back the Upgrade (Linux)
Rollback of the upgrade cannot be performed on Linux.
However, you can create a parallel system before upgrading and testing that system before attempting an upgrade. If you need to roll back the upgrade, you can revert back to that parallel system.
Multiple Instance Upgrades
In some deployment architectures Portal Server is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Portal Server components running on multiple computers with a load balancer to distribute the load.
In the case of load-balanced instances of Portal Server, you can perform a rolling upgrade in which you upgrade the Portal Server instances sequentially without interrupting service. You upgrade each instance of Portal Server while the others remain running. To perform a rolling upgrade from the IFR to Release 5U1, use the same procedure documented in Multiple Instance Upgrades, except substitute the IFR wherever Release 4 is referenced.
