Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Enterprise System 5 Upgrade Guide for UNIX 

Chapter 16
Portal Server Secure Remote Access

This chapter describes how to upgrade Portal Server Secure Remote Access to Java ES 5 (Release 5): Sun Java System Portal Server Secure Remote Access 7.1.

The chapter provides an overview of upgrade considerations for the different upgrade paths supported by Release 5. The chapter covers upgrades on both the Solaris and Linux operating systems:

Overview of Portal Server Secure Remote Access Upgrades

This section describes the following general aspects of Portal Server Secure Remote Access that impact upgrading to Java ES 5 (Release 5):

About Java ES Release 5 Portal Server Secure Remote Access

Portal Server Secure Remote Access (consisting of Gateway, Rewriter Proxy, Netlet Proxy components is closely coupled to Portal Server, though usually deployed on computers different from the one hosting Portal Server. Portal Server Secure Remote Access components use the same administrative infrastructure as Portal Server proper and interact with servlets and applets residing on the computer hosting Portal Server.

Java ES Release 5 Portal Server Secure Remote Access represents a major release with respect to Release 4, with many new enhancements and features. Many of these changes were made in an Interim Feature Release (IFR) subsequent to Release 4. Release 5 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 has been replaced by the psadmin command.

Portal Server Secure Remote Access Upgrade Roadmap

Table 16-2 shows the supported Portal Server Secure Remote Access upgrade paths to Java ES Release 5. The table applies to both Solaris and Linux operating systems.

Table 16-2  Upgrade Paths to Java ES 5 (Release 5): Portal Server Secure Remote Access 7.1  

Java ES Release

Portal Server Secure Remote Access Version

General Approach

Reconfiguration Required

Interim Feature Release (IFR)

Sun Java System Portal Server Secure Remote Access IFR 7.0 2005Q4

Direct upgrade:
Performed by applying patches and then using an upgrade script.

None.

Release 4

Sun Java System Portal Server Secure Remote Access 6.3.1 2005Q4

Direct upgrade:
Performed using an upgrade script.

None.

Release 3

Sun Java System Portal Server Secure Remote Access 6.3.1 2005Q1

Direct upgrade:
Performed using an upgrade script.

None.

Release 2

Sun Java System Portal Server Secure Remote Access
6.3 2004Q2

Direct upgrade:
Performed using an upgrade script.

None.

Release 1

Sun ONE Portal Server Secure Remote Access 6.2 (2003Q4)

No direct upgrade:
But can be performed by upgrading first to Release 3 and then upgrading from Release 3 to Release 5.

Configuration data

Pre-dates Java ES releases

 

No direct upgrade.

 

Portal Server Secure Remote Access Data

The following table shows the type of data that could be impacted by an upgrade of Portal Server Secure Remote Access software.

Table 16-3  Portal Server Secure Remote Access Data Usage 

Type of Data

Location

Usage

Configuration data

PortalServer6Config-base/

Configuration of Portal Server Secure Remote Access.

Directory schema

Services configuration

User data

Directory Server

Portal Server Secure Remote Access depends on services configurations, such as the portal desktop, and user profile data that is stored in a directory.

Dynamic application data

None

Portal Server Secure Remote Access does not persistently store application data such as session state.

Portal Server Secure Remote Access Upgrade Strategy

Your strategy for upgrading Portal Server Secure Remote Access 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 Secure Remote Access by presenting issues that might influence your Portal Server Secure Remote Access upgrade plan.

Compatibility Issues

Release 5 Portal Server Secure Remote Access introduces public interface changes in the psadmin command used to start and stop Gateway, Rewriter Proxy, and Netlet Proxy components. See the Sun Java System Portal Server 7.1 Command-Line Reference, http://docs.sun.com/doc/819-5030.

Individual Portal Server Secure Remote Access components (including the Gateway, the Rewriter Proxy, and the Netlet Proxy) are not backwardly compatible with earlier versions; all need to be synchronized, along with Portal Server itself, at Java ES Release 5. This requirement applies to Portal Server Secure Remote Access components that are local as well as distributed.

In addition, there is an incompatibility between the Directory Server data structures used by Release 5 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 Secure Remote Access Dependencies

Portal Server Secure Remote Access is closely coupled with Portal Server, depending on software packaged with Portal Server and running on the same computer as Portal Server.

However, Portal Server Secure Remote Access also depends on other Java ES components. These dependencies can impact your procedure for upgrading and re-configuring Portal Server Secure Remote Access software. Changes in Portal Server Secure Remote Access interfaces or functions, for example, could require upgraded version of components upon which Portal Server Secure Remote Access depends. The need to upgrade such components depends upon the specific upgrade path.

Portal Server Secure Remote Access components have dependencies on the following Java ES components:

Selective Upgrade Issues

While, in general, Java ES Release 5 supports selective upgrade of all components on a computer, the fact that Portal Server Secure Remote Access is closely tied to Portal Server means that Portal Server Secure Remote Access must be upgraded if Portal Server is upgraded. Similarly, upgrade of Portal Server Secure Remote Access requires that Portal Server also be upgraded.

As a result, the upgrade of Portal Server Secure Remote Access is bound by the same restrictions as Portal Server (see Portal Server Selective Upgrade Issues): you can either upgrade Portal Server Secure Remote Access and all of its product component dependencies to Release 5, or upgrade only Portal Server Secure Remote Access and Portal Server to Release 5, leaving other product component dependencies at Release 4.

Dual Upgrade

Dual upgrades, in which both Portal Server Secure Remote Access and operating system are upgraded (as described in Dual Upgrades: Java ES and Operating System Softwared) can be performed using the in-place operating system upgrade approach:

  1. Back up existing Portal Server Secure Remote Access data.

    2. See Portal Server Secure Remote Access Data for the location of essential data.

  2. Upgrade the operating system.

    3. The upgrade leaves the existing file system in place.

  3. Upgrade to Release 5 Portal Server Secure Remote Access.

    4. See the appropriate section of this chapter, depending on upgrade path.

Upgrading Portal Server Secure Remote Access from Java ES Release 4

This section includes information about upgrading Portal Server Secure Remote Access from Java ES 2005Q4 (Release 4) to Java ES 5 (Release 5).

The section covers the following topics:

Introduction

When upgrading Java ES Release 4 Portal Server Secure Remote Access to Release 5, consider the following aspects of the upgrade process:

Release 4 Portal Server Secure Remote Access Upgrade

This section describes how to perform an upgrade of Portal Server Secure Remote Access from Java ES Release 4 to Java ES Release 5 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 Secure Remote Access you should perform the following tasks:

Verify Current Version Information

You can verify the current version of Portal Server Secure Remote Access using the following command:

Upgrade Portal Server Secure Remote Access Dependencies

It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Java ES Release 5.

While Release 5 Portal Server Secure Remote Access 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 Secure Remote Access requires the Release 5 version of the ANT shared component.

In addition, Portal Server Secure Remote Access requires the upgrade of Portal Server. However it does not require upgrading other Java ES Release 4 product components upon which it depends.

In fact, your dependency upgrade approach is the same as that taken for Portal Server: if any of the dependencies are to be upgraded to Release 5, they all need to be upgraded (see Selective Upgrade Issues). However, because of the Portal Server Secure Remote Access dependency on Portal Server, the upgrade of Portal Server takes care of Portal Server Secure Remote Access dependencies, except, for shared components.

When you upgrade Portal Server Secure Remote Access dependencies to Release 5, the dependencies should be upgraded in the order below (skipping any that might already have been upgraded), before you upgrade Portal Server Secure Remote Access.

  1. Shared Components.  Instructions for synchronizing Java ES shared components to Release 5 are provided in Upgrading Java ES Shared Components.
  2. Portal Server.   Instructions for upgrading Portal Server are provided in Chapter 15, "Portal Server".
Back Up Release 4 Portal Server Secure Remote Access Configuration Information

Upgrade of Portal Server Secure Remote Access to Release 5 does not require the reconfiguration of Portal Server Secure Remote Access 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 Secure Remote Access 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 Secure Remote Access upgrade. This setting must therefore be modified before performing upgrade of any Portal Server Secure Remote Access components. To modify the LOAD_BALANCER_URL property setting:

  1. Note which of the following configuration files are locally resident (some of which support Portal Server components that might be locally installed):

    2. PortalServer6Config-base/PSConfig.properties  (if Portal Server is local)
    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)

  2. Record the current value of the LOAD_BALANCER_URL property in these configuration files.
  3. Modify the value of the LOAD_BALANCER_URL property to point to the corresponding Portal Server Secure Remote Access instance being upgraded:

    4. LOAD_BALANCER_URL=hostName:port/portal

  4. Make sure that the following configuration properties, if present, reference the relevant Portal Server Secure Remote Access component (and not the load balancer), as shown below:

    5. In PortalServer6Config-base/platform.conf.default file:

    gateway.host=Gateway_hostName

    In PortalServer6Config-base/GWConfig.properties and
        PortalServer6Config-base/GWConfig-default.properties files:

    GW_HOST=Gateway_hostName
    GW_IP=Gateway_hostIP

    In PortalServer6Config-base/RWPConfig.properties and
        PortalServer6Config-base/RWPConfig-default.properties files:

    RWP_HOST=RewriterProxy_hostName
    RWP_IP=RewriterProxy_hostIP

    In PortalServer6Config-base/NLPConfig.properties and
        PortalServer6Config-base/NLPConfig-default.properties files:

    NLP_HOST=NetLetProxy_hostName
    NLP_IP=NetLetProxy_hostIP

Remove Configuration for Directory Proxy Server

In cases in which Portal Server Secure Remote Access 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:

  1. Record the current value of the DS_HOST and DS_PORT properties in the following Access Manager configuration file:

    2. AccessManagerConfig-base/config/AMConfig.properties

  2. Modify the value of the DS_HOST and DS_PORT properties to point directly to the relevant Directory Server instance.
Obtain Required Configuration Information and Passwords

Depending on the upgrade scenario, the psupgrade script requires you to input information about the following admin accounts:

Upgrading Release 4 Portal Server Secure Remote Access (Solaris)

This section discusses considerations that impact the upgrade procedure for Portal Server Secure Remote Access followed by a description of the procedure itself.

Upgrade Considerations (Solaris)

The upgrade of Portal Server Secure Remote Access software to Release 5 takes into account the following considerations:

Upgrade Procedure (Solaris)

The procedure documented below applies to t he Portal Server Secure Remote Access component on the computer where the upgrade is taking place.

  1. Log in as root or become superuser.

    2. su -

  2. If you have not already done so, synchronize all shared components to Release 5.

    3. 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.

  3. Stop any instances of the Gateway, Rewriter Proxy, or Netlet Proxy that are running locally.

    4. PortalServer6-base/bin gateway stop
    PortalServer6-base/bin netletd stop
    PortalServer6-base/bin rwproxyd stop

    Check that the processes have stopped:

    Gateway: netstat -an | grep 443
    Rewriter Proxy: netstat -an | grep 10443
    Netlet Proxy: netstat -an | grep 10555

  4. Make sure Access Manager is running.
  5. Set two environment variables (ANT_HOME and JAVA_HOME) needed by the psupgrade script. For example,

    6. export ANT_HOME=/usr/sfw
    export JAVA_HOME=/usr/jdk/entsys-j2se

  6. Make sure you have adequate swap space on your computer.

    7. As a guideline, the swap space should be set to twice the amount of physical ram.

  7. If the Portal Server Secure Remote Access component you are upgrading is remote from Portal Server, copy the dpadmin executable from the computer hosting Portal Server to the computer hosting the Portal Server Secure Remote Access component.

    8. The dpadmin executable can be found in the following location:

    PortalServer7-base/SUNWps.bak/bin/dpadmin, if Portal Server has been upgraded.

    PortalServer6-base/bin/dpadmin, if Portal Server has not yet been upgraded.

  8. Run the psupgrade script from the Java ES Release 5 distribution.

    9. cd os_arch/Products/portal_svr/Tools/upgrade/bin
    ./psupgrade

    where os_arch matches your platform, such as Solaris_sparc.

    The psupgrade script invokes the Java ES installer to install new packages and requests the following information:

    • Directory Server Admin ID and password
    • Access Manager Admin ID and password
    • Directory Server amldapuser ID and password
  9. Start instances of the Gateway, Rewriter Proxy, or Netlet Proxy that were stopped in Step 3.

    10. PortalServer7-base/bin/psadmin start-sra-instance -u amadminUser
        -f     passwordFile --name default --type gateway

    PortalServer7-base/bin/psadmin start-sra-instance -u amadminUser
        -f     passwordFile --name default --type nlproxy

    PortalServer7-base/bin/psadmin start-sra-instance -u amadminUser
        -f     passwordFile --name default --type rwproxy

    If the above commands fail, you must first register (enable) Portal Server Secure Remote Access components:

    PortalServer7-base/bin/psadmin provision-sra -u amadminUser
        -f     passwordFile -p Portal_ID --gateway-profile profileName --enable

Upgrading Release 4 Portal Server Secure Remote Access (Linux)

This section discusses considerations that impact the upgrade procedure for Portal Server Secure Remote Access followed by a description of the procedure itself.

Upgrade Considerations (Linux)

The upgrade of Portal Server Secure Remote Access software to Release 5 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that Release 5 Portal Server Secure Remote Access 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 5 RPMs.

Upgrade Procedure (Linux)

The procedure documented below applies to Portal Server Secure Remote Access on the computer where the upgrade is taking place.

Caution

An upgrade from Java ES Release 4 to Release 5 on Linux cannot be rolled back. Make sure you back up your system before performing the following procedure.

  1. Log in as root or become superuser.

    2. su -

  2. If you have not already done so, synchronize all shared components to Release 5.

    3. 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.

  3. Stop any instances of the Gateway, Rewriter Proxy, or Netlet Proxy that are running locally.

    4. PortalServer6-base/bin gateway stop
    PortalServer6-base/bin netletd stop
    PortalServer6-base/bin rwproxyd stop

    Check that the processes have stopped:

    Gateway: netstat -an | grep 443
    Rewriter Proxy: netstat -an | grep 10443
    Netlet Proxy: netstat -an | grep 10555

  4. Make sure Access Manager is running.
  5. Set two environment variables (ANT_HOME and JAVA_HOME) needed by the psupgrade script. For example,

    6. export ANT_HOME=/opt/sun
    export JAVA_HOME=/usr/jdk/entsys-j2se

  6. Make sure you have adequate swap space on your computer.

    7. As a guideline, the swap space should be set to twice the amount of physical ram.

  7. If the Portal Server Secure Remote Access component you are upgrading is remote from Portal Server, copy the dpadmin executable from the computer hosting Portal Server to the computer hosting the Portal Server Secure Remote Access component.

    8. The dpadmin executable can be found in the following location:

    PortalServer7-base/SUNWps.bak/bin/dpadmin, if Portal Server has been upgraded.

    PortalServer6-base/bin/dpadmin, if Portal Server has not yet been upgraded.

  8. Run the psupgrade script from the Java ES Release 5 distribution.

    9. cd os_arch/Products/portal_svr/Tools/upgrade/bin
    ./psupgrade

    where os_arch matches your platform, such as Solaris_sparc.

    The psupgrade script invokes the Java ES installer to install new packages and requests the following information:

    • Directory Server Admin ID and password
    • Access Manager Admin ID and password
    • Directory Server amldapuser ID and password

Verifying the Upgrade

If the Portal Server Secure Remote Access component you are upgrading is remote from Portal Server, you can verify the installation of Release 5 packages by checking the version information in the following file:

However, if the Portal Server Secure Remote Access component you are upgrading is resides on the same computer as Portal Server, you can verify the upgrade using the following command:

See Table 16-4 for output values.

You can also check the upgrade log files at:

/var/sadm/install/logs/Sun_Java_System_Portal_Server_upagrede.log

Release 4 Post-Upgrade Tasks

There are no post-upgrade tasks required when upgrading Portal Server Secure Remote Access to Release 5, except for the following situations:

Restore Configuration for Load Balancer

If Portal Server Secure Remote Access instances have been accessed through a load balancer, the following steps need to be performed after upgrade to restore the load balancer configuration:

  1. Set the following parameters in the PortalServer7Config-base/platform.conf.default file:

    2. gateway.virtualhost=loadBalancer_hostName loadBalancer_hostIP
    gateway.external.ip=    loadBalancer_hostIP
    gateway.dsame.agent=http\://loadBalancer_hostName\:
        80/portal/RemoteConfigServlet

  2. Set the following parameter in the PortalServer7Config-base/GWConfig-default.properties file.

    3. gateway.ipaddress=Gateway_hostIP

  3. Set the parameters corresponding to Step 1 and Step 2 for Rewriter Proxy and Netlet Proxy, when these instances are deployed on computers remote from the Portal Server host.
  4. Restart Portal Server and the load-balanced Portal Server Secure Remote Access instances.
Restore Configuration for Directory Proxy Server

If Portal Server Secure Remote Access 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 were modified in preparation for upgrade.

Delete Release 4 Localized Providers

Localized Proxylet services will not load until you delete the Release 4 localized providers, as follows:

  1. Go to the PortalServer7Data-base/portals/Upgraded/desktop directory.
  2. Delete all directories and files from default_Locale except for:
    • Files and directories you have created (not shipped with Portal Server Secure Remote Access)
    • The message.properties file
    • The following directories:

      • AddressBookProvider
      BookmarkProvider
      CalendarProvider
      LoginProvider
      LotusNotesAddressBookProvider
      LotusNotesCalendarProvider
      LotusNotesMailProvider
      MSExchangeAddressBookProvider
      MSExchangeCalendarProvider
      MSExchangeMailProvidervMailProvider
      NotesProvider
      PersonalNoteProvider
      Register
      SampleRSS
      SampleURLScraper
      SampleXML
      TemplateEditContainerProvider
      TemplateTabContainerProvider
      URLScraperProvider
      UWCAddressBookProvider
      UserInfo
      UserInfoProvider
      XMLProvider
      error

  3. Restart the web container. in which Portal Server is deployed.

Rolling Back the Upgrade (Solaris)

This section describes considerations that impact the upgrade rollback procedure for Portal Server Secure Remote Access followed by the procedure itself.

Rollback Considerations (Solaris)

The procedure for rolling back the upgrade to Release 5 consists of reverting back to the Release 4 installation at PortalServer6-base.

Rollback Procedure (Solaris)
  1. Log in as root or become superuser.

    2. su -

  2. Restore Directory Server to the state it was in before upgrade.

    3. 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.

  3. Remove the Release 5 Portal Server Secure Remote Access packages.
    1. Launch the Java ES uninstaller.

      2. /var/sadm/prod/SUNWentsys5/uninstall

    2. Select all installed Portal Server Secure Remote Access components.
    3. Confirm your uninstall choice.
    4. Exit the Java ES uninstaller.
  4. Restore the PortalServer6-base and PortalServer6Config-base directories to their original locations.

    5. During upgrade they were move to directories with a .bak extension.

Rolling Back the Upgrade (Linux)

Because the upgrade to Release 5 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 Secure Remote Access components, such as Gateway, are deployed on multiple computer systems to provide for security and scalability and to improve availability. For example, you might have Gateway components running on multiple computers with a load balancer to distribute the load.

In the case of load-balanced instances of Gateway, you can perform a rolling upgrade in which you upgrade Gateway instances sequentially without interrupting service, as described below. The procedure takes into account the following constraint: individual Portal Server Secure Remote Access components are not backwardly compatible with earlier versions; all need to be synchronized, along with Portal Server itself, at Java ES Release 5. However during a rolling upgrade Release 4 Portal Server Secure Remote Access instances can remain running while Portal Server instances are being upgraded.

The deployment architecture shown in Figure 16-1 will be used to illustrate the rolling upgrade procedure.

In this architecture, multiple Portal Server instances are accessed by way of Portal Server Secure Remote Access Gateway instances. Both the Portal Server instances and the Gateway instances are load balanced to provide for availability and scalability.

The Portal Server instances, in turn, access Access Manager instances through a load balancer. 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 16-1, the multiple instances of Gateway, 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 16-1  Example Deployment Architecture for Multiple Portal Server Instances

Diagram showing example deployment architecture for multiple Gateway instances which access multiple Portal Server instances which access multiple Access Manager instances.

Rolling upgrade of Release 4 Gateway (and Portal Server) to Release 5 is performed as follows:

  1. If you are upgrading Release 4 Access Manager to Release 5, perform a rolling upgrade as documented in Multiple Instance Upgrades. Note that in upgrading Release 4 Gateway or Release 4 Portal Server to Release 5, you are not required to upgrade Release 4 Access Manager to Release 5.
  2. Modify the configuration of Portal Server and Gateway instances as follows.
    1. Configure Portal Server 2 to point to Directory Server 2 rather than Directory Server 1.

      2. For brevity, in this and succeeding steps, “Portal Server 2” will mean Portal Server 2 through Portal Server n.

    2. Configure Gateway 2 to point to Directory Server 2 rather than Directory Server 1.

      3. For brevity, in this and succeeding steps, “Gateway 2” will mean Gateway 2 through Gateway n.

  3. Upgrade Portal Server 1.
    1. Disable Portal Server 1 in Load Balancer B.

      2. Requests will no longer be routed to Portal Server 1.

    2. Disable Directory Server MMR.

      3. Directory Server 2 will no longer by synchronized with Directory Server 1.

    3. Upgrade Access Manager SDK 1B to Release 5.

      4. Use the procedure in Release 4 Access Manager SDK-only Upgrades.

    4. Upgrade Portal Server 1 to Release 5.

      5. Perform the upgrade of the Portal Server instance as described in Release 4 Portal Server Secure Remote Access 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 5.

  4. Upgrade Gateway 1.
    1. Disable Gateway 1 in Load Balancer C.

      2. Requests will no longer be routed to Gateway 1.

    2. Upgrade Access Manager SDK 1A to Release 5.

      3. Use the procedure in Release 4 Access Manager SDK-only Upgrades.

    3. Upgrade Gateway 1 to Release 5.

      4. Perform the upgrade of Gateway as described in Release 4 Portal Server Secure Remote Access 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.
  5. Enable the previously disabled Portal Server 1 and Gateway 1 in their respective load balancers, as follows:
    1. Enable Portal Server 1 in Load Balancer B.

      2. Requests will be once again routed to Portal Server 1.

    2. Enable Gateway 1 in Load Balancer C.

      3. Requests will be once again routed to Gateway 1.

  6. Disable Portal Server 2 and Gateway 2 in their respective load balancers, as follows:
    1. Disable Portal Server 2 in Load Balancer B.

      2. Requests will no longer be routed to Portal Server 2.

    2. Disable Gateway 2 in Load Balancer C.

      3. Requests will no longer be routed to Gateway 2.

  7. Upgrade Portal Server 2.
    1. Restore the configuration of Portal Server 2 to point to Directory Server 1.
    2. Upgrade Access Manager SDK 2B to Release 5.

      3. Use the procedure in Release 4 Access Manager SDK-only Upgrades.

    3. Upgrade Portal Server 2 to Release 5.

      4. Use the same procedure as in Upgrade Portal Server 1, Step d.

    4. Enable Portal Server 2 in Load Balancer B.

      5. Requests will be once again routed to Portal Server 2.

  8. Upgrade Gateway 2.
    1. Restore the configuration of Gateway 2 to point to Directory Server 1.
    2. Upgrade Access Manager SDK 2A to Release 5.

      3. Use the procedure in Release 4 Access Manager SDK-only Upgrades.

    3. Upgrade Gateway 2 to Release 5.

      4. Use the same procedure as in Upgrade Gateway 1, Step c.

    4. Enable Gateway 2 in Load Balancer C.

      5. Requests will be once again routed to Gateway 2.

  9. Enable Directory Server MMR.

    10. The Portal Server data for Directory Server 2, is now synchronized with Directory Server 1.

    Note

    In rolling upgrades scenarios in which Portal Server instances are being upgraded to Release 5 while earlier releases of the Gateway component remain active (which is not the case in the above procedure), and in which Gateway instances are accessed through a load balancer, you should check for all Gateway instances that the following configuration properties in the PortalServer6Config-base/GWConfig.properties file and GWConfig-default.properties file reference the Gateway and not the load balancer:

    GW_IP=Gateway_hostIP
    GW_HOST=Gateway_hostName

    If these properties point to the load balancer, the Gateway will no longer access upgraded Portal Server instances.

Upgrading Portal Server Secure Remote Access from Java ES Release 3

The procedure for upgrading Java ES 2005Q1 (Release 3) Portal Server Secure Remote Access to Release 5 is the same as that for upgrading Release 4 Portal Server Secure Remote Access to Release 5, with the following exceptions:

Upgrading Portal Server Secure Remote Access Dependencies

However, when upgrading Portal Server Secure Remote Access from Release 3, you have to upgrade Access Manager to Release 4 or to Release 5 before upgrading Portal Server Secure Remote Access, and you cannot leave any other dependencies at Release 3, nor upgrade some dependencies to Release 4 and others to Release 5. For more information, see Selective Upgrade Issues.

The following dependencies need to be upgraded in the order shown below.

  1. Shared Components.  Instructions for upgrading Java ES shared components to Release 5 are provided in Chapter 2, "Upgrading Java ES Shared Components".
  2. Directory Server.  Instructions for upgrading Directory Server to Release 5 are provided in Upgrading Directory Server from Java ES Release 2.
  3. Access Manager (Access Manager SDK).  Instructions for upgrading Access Manager to Release 5 are provided in Chapter 14, "Access Manager".
  4. Portal Server.   Instructions for upgrading Portal Server are provided in Chapter 15, "Portal Server".

Upgrading Release 3 Portal Server Secure Remote Access

To upgrade Release 3 Portal Server Secure Remote Access to Release 5, use the instructions in Upgrading Portal Server Secure Remote Access from Java ES Release 4, except substitute Release 3 wherever Release 4 is referenced.

Multiple Instance Upgrades

In some deployment architectures Portal Server Secure Remote Access components, such as Gateway, are deployed on multiple computer systems to provide for security and scalability and to improve availability. For example, you might have Gateway components running on multiple computers with a load balancer to distribute the load.

When performing multiple instance upgrades from Release 3 Portal Server Secure Remote Access, use the procedure documented in Multiple Instance Upgrades, except replace “Release 4” with “Release 3” wherever Release 4 is referenced. You must also upgrade Access Manager, as described in Step 1.

Upgrading Portal Server Secure Remote Access from Java ES Release 2

This section includes information about upgrading Java ES 2004Q2 (Release 2) Portal Server Secure Remote Access to Release 5. The upgrade procedure is similar to that for upgrading Release 4 Portal Server Secure Remote Access to Release 5, except for some changes as documented in the following sections:

Release 2 Pre-Upgrade Tasks

The pre-upgrade tasks for upgrading Portal Server Secure Remote Access from Release 2 are the same as those documented in Release 4 Pre-Upgrade Tasks, except for the following tasks:

Upgrading Portal Server Secure Remote Access Dependencies

When upgrading Portal Server Secure Remote Access from Release 2, you have to upgrade Access Manager to Release 4 or to Release 5 before upgrading Portal Server Secure Remote Access, and you cannot leave any other dependencies at Release 2, nor upgrade some dependencies to Release 4 and others to Release 5. For more information, see Selective Upgrade Issues.

The following dependencies need to be upgraded in the order shown below.

  1. Shared Components.  Instructions for upgrading Java ES shared components to Release 5 are provided in Chapter 2, "Upgrading Java ES Shared Components". However, if shared components have not yet been upgraded, they will be upgraded automatically by the psupgrade script.
  2. Directory Server.  Instructions for upgrading Directory Server to Release 5 are provided in Upgrading Directory Server from Java ES Release 2.
  3. Access Manager (Access Manager SDK).  Instructions for upgrading Access Manager to Release 5 are provided in Chapter 14, "Access Manager".
  4. Portal Server.   Instructions for upgrading Portal Server are provided in Chapter 15, "Portal Server".

To upgrade Release 2 Portal Server Secure Remote Access to Release 5, use the instructions in Upgrading Portal Server Secure Remote Access from Java ES Release 4, except substitute Release 2 wherever Release 4 is referenced.

Delete Gateway Service Entry

The amService-srapGateway user entry must be manually deleted when upgrading Portal Server from Release 2, otherwise the Gateway will fail to start after upgrade. Perform the following steps:

  1. Log in to Access Manager Console.
  2. List all users in the organization DN.
  3. Delete the amService-srapGateway user.

Upgrading Release 2 Portal Server Secure Remote Access

The procedure for upgrading Java ES 2004Q2 (Release 2) Portal Server Secure Remote Access to Release 5 is the same as for upgrading Release 4 Portal Server Secure Remote Access to Release 5.

To upgrade Release 2 Portal Server Secure Remote Access to Release 5, use the instructions in Upgrading Portal Server Secure Remote Access from Java ES Release 4, except substitute Release 2 wherever Release 4 is referenced.

Release 2 Post-Upgrade Tasks

The post-upgrade tasks for upgrading from Release 2 are the same as those documented in Release 4 Post-Upgrade Tasks, except for the following task:

Set Portal Server Domain for Proxylet Service

After upgrading Release 2 Portal Server Secure Remote Access to Release 5, you have to set the correct Portal Server domain value.

  1. Log in to Portal Server Console, and navigate to the Proxylet tab under Secure Remote Access.
  2. Select the distinguished name (DN) of the Organization where the Proxylet service is found.
  3. Under the Domains field of Proxylet rules, replace SERVER_DOMAIN with the domain name where Portal Server is installed.
  4. Repeat the above steps for all organizations where Proxylet is service is found.

Multiple Instance Upgrades

Multiple instance rolling upgrades (seeMultiple Instance Upgrades) are not supported in upgrading Release 2 Portal Server Secure Remote Access components (or Portal Server) to Release 5.

Upgrading Portal Server Secure Remote Access from the Interim Feature Release 7.0

This section includes information about upgrading Portal Server Secure Remote Access from the Interim Feature Release (IFR) 7.0 2005Q4 to Java ES 5 (Release 5).

The section covers the following topics:

Introduction

When upgrading Portal Server Secure Remote Access IFR 7.0 to Release 5, consider the following aspects of the upgrade process:

The psupgrade script for upgrading Portal Server Secure Remote Access IFR to Release 5 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 patches:

Table 16-5  Patches1 to Upgrade Portal Server Secure Remote Access IFR to Release 5 

Description

Patch ID: Solaris 9 & 10

Patch ID: Linux

Portal Server 7.1

121465-10 (SPARC)

121466-10 (x86)

121467-10

Portal Server 7.1
localization

123254-02 (SPARC)

124590-02 (x86)

123255-02

1Patch revision numbers are the minimum required for upgrade to Java ES Release 5. If newer revisions become available, use the newer ones instead of those shown in the table.

Portal Server Secure Remote Access IFR 7.0 Upgrade

This section describes how to perform an upgrade of Portal Server Secure Remote Access from the IFR to Java ES Release 5 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

Pre-upgrade tasks for the IFR upgrade are the same as for the Release 4 upgrade (see Release 4 Pre-Upgrade Tasks).

Upgrading Portal Server Secure Remote Access IFR 7.0 (Solaris)

This section discusses considerations that impact the upgrade procedure for Portal Server Secure Remote Access followed by a description of the procedure itself.

IFR 7 Upgrade Considerations (Solaris)

The Portal Server Secure Remote Access IFR upgrade to Release 5 takes into account the same considerations as the Release 4 upgrade (see Upgrade Considerations (Solaris)).

IFR 7 Upgrade Procedure (Solaris)

The procedure documented below applies to Portal Server Secure Remote Access on the computer where the upgrade is taking place.

  1. Log in as root or become superuser.

    2. su -

  2. Stop any instances of the Gateway, Rewriter Proxy, or Netlet Proxy that are running locally.

    3. PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
       -f     passwordFile -t gateway -N gatewayProfileName

    PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
       -f     passwordFile -t rwproxy -N gatewayProfileName

    PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
       -f     passwordFile -t nlproxy -N gatewayProfileName

    Check that the processes have stopped:

    Gateway: netstat -an | grep 443
    Rewriter Proxy: netstat -an | grep 10443
    Netlet Proxy: netstat -an | grep 10555

  3. Make sure Access Manager is running.
  4. Obtain the required patch, based on Table 16-5.

    5. Always use the latest patch revision available, unless directed to use a specific revision.

    Patches can be downloaded to /tmp from: http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access

  5. Apply the appropriate Portal Server patch and, if needed, localization patch in Table 16-5.

    6. patchadd patch_ID

  6. Confirm that the patch upgrade was successful:

    7. showrev -p | grep patch_ID

    The output should return the versions of patch IDs applied in Step 5.

  7. In cases where localization packages have been upgraded in Step 5, set the Portal Server Console JVM's locale to UTF-8.

    8. export LC_ALL=ja_JP.UTF-8
    export LANG=ja_JP.UTF-8

  8. Set two environment variables (ANT_HOME and JAVA_HOME) needed by the psupgrade script:

    9. export ANT_HOME=/usr/sfw
    export JAVA_HOME=/usr/jdk/entsys-j2se

  9. Make sure you have adequate swap space on your computer.

    10. As a guideline, the swap space should be set to twice the amount of physical ram.

  10. Run the psupgrade script.

    11. cd PortalServer7-base/bin
    ./psupgrade

    The psupgrade script is not run from the Java ES Release 5 distribution and does not invoke the Java ES installer (the packages were already patched).

Upgrading Portal Server Secure Remote Access IFR 7.0 (Linux)

This section discusses considerations that impact the upgrade procedure for Portal Server Secure Remote Access followed by a description of the procedure itself.

IFR 7 Upgrade Considerations (Linux)

The upgrade of Portal Server Secure Remote Access software to Release 5 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that installing the Release 5 patches on Linux OS removes the previous RPMs.

IFR 7 Upgrade Procedure (Linux)

The procedure documented below applies to Portal Server Secure Remote Access on the computer where the upgrade is taking place.

Caution

An upgrade from Portal Server Secure Remote Access IFR to Release 5 on Linux cannot be rolled back. Make sure you back up your system before performing the following procedure.

  1. Log in as root or become superuser.

    2. su -

  2. Stop any instances of the Gateway, Rewriter Proxy, or Netlet Proxy that are running locally.

    3. PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
       -f     passwordFile -t gateway -N gatewayProfileName

    PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
       -f     passwordFile -t rwproxy -N gatewayProfileName

    PortalServer7-base/bin/psadmin stop-sra-instance -u amadminUser
       -f     passwordFile -t nlproxy -N gatewayProfileName

    Check that the processes have stopped:

    Gateway: netstat -an | grep 443
    Rewriter Proxy: netstat -an | grep 10443
    Netlet Proxy: netstat -an | grep 10555

  3. Make sure Access Manager is running.
  4. Obtain the required patch using the patch numbers and RPM names from Table 16-5.

    5. Always use the latest patch revision available, unless directed to use a specific revision.

    Patches can be downloaded to /tmp from: http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access

  5. Apply the Portal Server patch and, if needed, localization RPMs for Portal Server in Table 16-5, in that order.

    6. See the Readme file for the Portal Server patch, which describes how to use a script to apply the patch’s RPMs:

    cd /tmp

    where /tmp is the directory to which you download the patch.

    ./update

    The update script installs the RPM’s.

    For the localization patch, install each RPM using the following command:

    rpm -Fvh patchName-version.rpm

  6. Confirm that the patch upgrade was successful:

    7. rpm -qa | grep sun-portal-core

    The upgrade revision numbers of the RPMs should be returned.

  7. In cases where localization packages have been upgraded in Step 5, set the Portal Server Console JVM's locale to UTF-8.

    8. export LC_ALL=ja_JP.UTF-8
    export LANG=ja_JP.UTF-8

  8. Set two environment variables (ANT_HOME and JAVA_HOME) needed by the psupgrade script:

    9. export ANT_HOME=/opt/sun
    export JAVA_HOME=/usr/jdk/entsys-j2se

  9. Make sure you have adequate swap space on your computer.

    10. As a guideline, the swap space should be set to twice the amount of physical ram.

  10. Run the psupgrade script.

    11. cd PortalServer7-base/bin
    ./psupgrade

    The psupgrade script is not run from the Java ES Release 5 distribution and does not invoke the Java ES installer (the packages were already patched).

Verifying the Upgrade

You can verify the patching of Portal Server Secure Remote Access packages to Release 5 using the following command:

See Table 16-4 for output values.

You can also check the upgrade log files at:

/var/sadm/install/logs/Sun_Java_System_Portal_Server_upagrede.log

Post-Upgrade Tasks

There are no post-upgrade tasks required when upgrading Portal Server Secure Remote Access to Release 5.

Rolling Back the Upgrade (Solaris)

This section describes considerations that impact the upgrade rollback procedure for Portal Server Secure Remote Access followed by the procedure itself.

Rollback Considerations (Solaris)

The procedure for rolling back the upgrade to Release 5 consists of reverting back to the IFR installation at PortalServer7-base.

Rollback Procedure (Solaris)
  1. Log in as root or become superuser.

    2. su -

  2. Restore Directory Server to the state it was in before upgrade.

    3. 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.

  3. Back out the Portal Server 7.1 patch in Table 16-5.

    4. patchrm patch_ID

Rolling Back the Upgrade (Linux)

On the Linux platform there is no procedure for rolling back the upgrade.

Multiple Instance Upgrades

In some deployment architectures Portal Server Secure Remote Access is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Portal Server Secure Remote Access components running on multiple computers with a load balancer to distribute the load.

In the case of load-balanced instances of Portal Server Secure Remote Access, you can perform a rolling upgrade in which you upgrade the Portal Server Secure Remote Access instances sequentially without interrupting service. You upgrade each instance of Portal Server Secure Remote Access while the others remain running. You perform the upgrade of each instance as described in Portal Server Secure Remote Access IFR 7.0 Upgrade.

When performing multiple instance upgrades from IFR Portal Server Secure Remote Access, use the procedure documented in Multiple Instance Upgrades, except replace “Release 4” with “IFR” wherever Release 4 is referenced. You must also upgrade Access Manager, as described in Step 1.



Previous      Contents      Index      Next     

Part No: 819-6553-11
June 2007.   Copyright 2007 Sun Microsystems, Inc. All rights reserved.