Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Enterprise System 2004Q2 Installation Guide 

Chapter 8
Upgrading from Java Enterprise System 2003Q4

This chapter provides the procedures to upgrade component products from the Java Enterprise System 2003Q4 release for the Solaris operating system to the Java Enterprise System 2004Q2 release for the Solaris operating system. For procedures to upgrade from releases earlier than those contained inJava Enterprise System 2003Q4, see Upgrading Components from Versions Predating Java Enterprise System.

This chapter contains the following sections:

Preparing for Upgrades

In preparing to upgrade your servers, note the following:

Product Dependencies

Many component products depend on other products to be upgraded before they are upgraded. See Determining Your Upgrade Needs for information necessary to list or diagram the chain of dependencies that determines your upgrade process.

The following list the products in the order that they should be upgraded. Find the products appropriate to your situation and upgrade them in this order.

  1. Sun Cluster (See Sun Cluster Upgrade Information)
  2. Shared Components (See Upgrading Shared Components)
  3. Administration Server (See Administration Server Upgrade Information)
  4. Directory Server (See Directory Server Upgrade Information)
  5. Directory Proxy Server (See Directory Proxy Server Upgrade Information)
  6. Web Server (See Web Server Upgrade Information)
  7. Message Queue (See Message Queue Upgrade Information)
  8. Application Server (See Application Server Upgrade Information)
  9. Identity Server (See Identity Server Upgrade Information
  10. Messaging Server (See Messaging Server Upgrade Information)
  11. Calendar Server (See Calendar Server Upgrade Information)
  12. Portal Server (See Portal Server Upgrade Information)
  13. Instant Messaging (See Instant Messaging Upgrade Information)
  14. Mobile Access Mobile Access Upgrade Information
  15. Sun Cluster agents (See Sun Cluster Upgrade Information)

Upgrading Shared Components

All component products except Sun Cluster require that the Java Enterprise System 2004Q2 shared components be updated. This section details these procedures in the following sections:

Applying Patch Clusters

To upgrade the shared components there are four shared component clusters which you will need to apply depending on which version of Solaris you are running. They are:

Patch Contents lists the contents of each patch cluster.

    To Apply Shared Components Patch Clusters
  1. To obtain the shared component cluster go to SunSolve and download it; see:

    2. http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access

  2. Become root by running su and entering the super-user password.
  3. Read the README which will contain important instructions and other last minute information about the patch.
  4. Run the install_cluster script which will install all the appropriate patches.

    5. The README contains the specific instructions for installing the patch.

    Note

    When installing the patch clusters, install the cluster specific to your OS version first and then install Java Enterprise System 2004Q2 required shared component patch cluster specific to your operating system.

    You can obtain the patches individually and install them if you prefer. In this case you should obtain each patch individually from SunSolve and follow the installation instructions for that patch.

    In some cases, the following patches included in the Java Enterprise System Required component patch clusters may detect a condition which requires manual intervention. To resolve this issue please follow the instructions in the patch cluster README file and the individual patch README files.

    SPARC

    • 116296-10: Sun One Application Server Java Activation Framework Patch
    • 116298-10: Sun One Application Server Java API for XML Parsing 1.2 Patch
    • 116300-10: Sun One Application Server Java Mail Runtime Patch

Upgrading J2SE Packages

This section contains the following procedures:

    To Determine Your J2SE Version
  1. Become root by running su and entering the super-user password.
  2. Determine if you need to install a new version of J2SE or reuse an existing installation of J2SE.

    3. Determine the version of J2SE installed in the default location of your system by entering:

    # /usr/jdk/entsys-j2se/bin/java -fullversion

    Note

    If the version is equal to or greater than 1.4.2_04 and less than 1.5, then you may reuse the existing installation of J2SE in support of Java Enterprise System 2004Q2. If this is the case, then follow the procedures in To Set the J2SE Symbolic Link to shutdown necessary services, reset a symbolic link and restart the services respectively.

    If the version is less than 1.4.2_04, perform the steps in:

    To Obtain J2SE 1.4.2
  1. To obtain J2SE 1.4.2 either obtain the packages from either of the following sources:
    To Determine Where to Install the J2SE Packages
  1. Inspect the symbolic link /usr/jdk/entsys-j2se to determine the location of J2SE as used by Java Enterprise System as follows:

    2. # ls -l /usr/jdk/entsys-j2se

    If the link points to the location /usr/j2se, then you need to upgrade the copy of J2SE installed under /usr/j2se, the default installation location for J2SE 1.4 on Solaris. If the link points to /usr/jdk/.j2se1.4.1_06 or similar, then you have the option of either installing J2SE 1.4.2 under /usr/jdk or upgrading the installation of J2SE installed in the default install location of /usr/j2se.

    Note

    Upgrading the version of J2SE installed in the default location, /usr/j2se, is easier than installing an additional instance of the J2SE packages. However, if you have any applications that depend on the specific version of J2SE installed under the default location, you may wish to leave that version intact and install an additional instance of the J2SE packages.

    To Install the J2SE Packages
  1. Shutdown Java Enterprise System services that depend on J2SE.
  2. Install the J2SE Packages contained in the Java Enterprise System 2004Q2 distribution.

    3. The new version of J2SE that has been certified with Java Enterprise System 2004Q2 components is located under the following directory in the Java Enterprise System 2004Q2 distribution or 1.4.2 download:

    Solaris_arch/Product/shared_components/Packages

    The packages named SUNWj3* are the packages that make up J2SE.

    Based on the results of To Determine Where to Install the J2SE Packages, follow the instructions in one of the following two sections:

    1. To upgrade Version Installed Under /usr/j2se
      1. Set your system to single user mode.
      2. Remove the existing packages:

        3. pkgrm SUNWj3dmo SUNWj3man SUNWj3dev SUNWj3rt

      3. Add the packages for the new version of J2SE:

        4. From within the directory containing the new version of J2SE in the Java Enterprise System 2004Q2 distribution or 1.4.2 download, execute the following command:

        pkgadd -d . SUNWj3rt SUNWj3cfg SUNWj3dev SUNWj3man SUNWj3dmo SUNWj3dvx SUNWj3jmp SUNWj3rtx

        The packages SUNWj3dvx and SUNWj3rtx are required only for 64-bit support while the package SUNWj3jmp is required only for Japanese man page support.

    2. To install a new version under /usr/jdk

      3. Installing an additional instance of J2SE packages is more involved than upgrading the installation of J2SE installed under the default location, /usr/j2se.

      1. Create an installation administration file to specify the non-default installation location of J2SE:

        2. # cp /var/sadm/install/admin/default /tmp/admin-file

        Edit the file /tmp/admin-file and change the following line from:

        basedir=default

        to:

        basedir=/usr/jdk/.j2se1.4.2_04

        All other settings within this file may remain intact.

        For more information on the use of an installation administration file to install packages in non-default locations, see the pkgadd(1) and admin(4) man pages for information on installing the SDK in a non-default location.

      2. Using the customized installation administration file, add the packages for the new version of J2SE:

        3. From within the directory containing the new version of J2SE in the Java Enterprise System 2004Q2 distribution or 1.4.2 download, execute the following command:

        pkgadd -a /tmp/admin-file -d . SUNWj3rt SUNWj3cfg SUNWj3dev SUNWj3man SUNWj3dmo SUNWj3dvx SUNWj3jmp SUNWj3rtx

        The packages SUNWj3dvx and SUNWj3rtx are required only for 64-bit support while the package SUNWj3jmp is required only for Japanese man page support.

      3. Add a symbolic link to represent the JAVA_HOME location of the newly installed J2SE by entering:

        4. # ln -s /usr/jdk/.j2se1.4.2_04/j2se /usr/jdk/j2se1.4.2_04

        Note the leading “.” in the first argument: “.j2se1.4.2_04”

    To Set the J2SE Symbolic Link
  1. Shutdown Java Enterprise System services that depend on J2SE.
  2. Reset the /usr/jdk/entsys-j2se symbolic link to point to the new J2SE installation.

    3. If you upgraded the version of J2SE installed under /usr/j2se, then reset the symbolic link as follows:

    # rm /usr/jdk/entsys-j2se
    # ln -s /usr/j2se /usr/jdk/entsys-j2se

    If you installed the new version of J2SE in the non-default location, then reset the symbolic link as follows:

    # rm /usr/jdk/entsys-j2se
    # ln -s /usr/jdk/j2se1.4.2_04 /usr/jdk/entsys-j2se

  3. Start Java Enterprise System services that depend on J2SE.
    To Upgrade Supplemental Files
  1. Acquire and load the Supplementary files for upgrading Sun Java Enterprise System from 2003Q4 to 2004Q2 for Application Server and Message Queue. For an evaluation copy go to:

    2. http://metis.red.iplanet.com:1088/iw-mount/default/main/sunSoftware/
    WORKAREA/_downloads/.preview/downloads/production/40b28b91.html

    If you already have an account with SunSolve go to:

    http://javashoplm.sun.com/ECom/docs/Welcome.jsp?StoreId=8&
    PartDetailId=JES2-AS-MQ-UPG-OTH-G-F&TransactionId=try

  2. Follow the instructions in the README file to install these Supplementary files.

Patch Contents

Table 8-1 through Table 8-4 list the shared component cluster contents and descriptions.

Note

All patches referred to in this section are the minimum version number required for upgrade. It is possible that a new version of the patch has been issued since this document was published. A newer version is indicated by a different version number at the end of the patch. For example: 123456-04 is a newer version of 123456-02 but they are the same patch ID. Refer to the README file for each patch listed for special instructions.

Table 8-1  Shared Component Patch Solaris 8/9 SPARC 

Patch ID

Description

116296-10

Sun One Application Server Java Activation Framework Patch

116298-10

Sun One Application Server Java API for XML Parsing 1.2 Patch

116300-10

Sun One Application Server Java Mail Runtime Patch

116585-10

SunOS5.8 SunOS5.9: Sun ONE commcli core patch

117024-02

ktsearch 1.3 ktsearch 1.3_x86: KT Search Engine

Table 8-2  Shared Required Component Patch Solaris 8 SPARC 

Patch ID

Description

114045-10

NSPR 4.1.6 / NSS 3.3.4.4

115328-01

Simple Authentication and Security Layer (2.01)

115924-08

NSPR 4.1.6 / NSS 3.3.10 / JSS 3.1.3

116103-04

SunOS 5.8: International Components for Unicode Patch

Table 8-3  Shared Component Patch Solaris 9 SPARC 

Patch ID

Description

114049-11

SunOS 5.9: NSPR 4.1.6 / NSS 3.3.4.4

114677-06

SunOS 5.9: International Components for Unicode Patch

115342-01

SunOS 5.9: Simple Authentication and Security Layer (2.01)

115926-08

SunOS 5.9: NSPR 4.1.6 / NSS 3.3.10 / JSS 3.1.3

Table 8-4  Shared Component Patch Solaris 9 x86 

Patch ID

Description

114050-10

SunOS 5.9_x86: NSPR 4.1.6 / NSS 3.3.4.4

114678-06

SunOS 5.9_x86: International Components for Unicode Patch

115927-08

SunOS 5.9_x86: NSPR 4.1.6 / NSS 3.3.10 / JSS 3.1.3

116297-10

Sun One Application Server 7.0_x86: Java Activation Framework Patch

116586-10

SunOS5.9_x86: Sun ONE commcli core patch

117024-02

ktsearch 1.3 ktsearch 1.3_x86: KT Search Engine

116299-10

Sun One Application Server 7.0_x86: Java API for XML

116301-10

Sun One Application Server 7.0_x86: Java Mail Runtime

Administration Server Upgrade Information

You upgrade Administration Server by applying patches, and synchronizing settings with the configuration directory server. This section contains:

    To Apply Administration Server Patches
  1. Obtain the patches for your platform and installed server component products.

    2. Required patches for SPARC� platforms include:

  2. Log in as or become superuser (root).
  3. Stop running servers in the following order:
    1. Calendar Server
    2. Messaging Server
    3. Directory Proxy Server
    4. Directory Server
    5. Administration Server

      6. Refer to Starting and Stopping Component Products for instructions on starting and stopping servers.

  4. Apply the Recommended Patch Cluster for your platform using the patchadd(1M) command.
  5. Apply the patches listed in Step 1 for all servers installed, even if those servers are not configured, in the following order using the patchadd(1M) command.
    1. Administration Server
    2. Directory Server (follow product specific instructions in Directory Server Upgrade Information)
    3. Directory Proxy Server (follow product specific instructions in Directory Proxy Server Upgrade Information)

      4. Note

      If you use Identity Server in association with Messaging Server and / or Calendar Server, please upgrade Identity Server (see Identity Server Upgrade Information) and Communications Services User Management Utility (this is upgraded with Upgrading Shared Components and configured in To Upgrade the User Management Utility before progressing.

    4. Messaging Server (follow product specific instructions in Messaging Server Upgrade Information)
    5. Calendar Server (follow product specific instructions in Calendar Server Upgrade Information)
  6. Restart the servers in the same order as for Step 5.

    7. Note

    To restart the Directory Server that shipped with Java Enterprise System enter:

    directoryserver -d 5.2 start

  7. If Administration Server is configured, synchronize the upgraded Administration Server settings with those stored in the configuration directory server using the mpsadmserver(1M) command.

    8. # /usr/sbin/mpsadmserver sync-cds

    The configuration directory server must be available for this step to complete properly.

    To Remove Administration Server Patches

Remove patches on all servers you installed in To Apply Administration Server Patches by:

  1. If Administration Server is configured, return to the pre-patch settings stored in the configuration directory using the mpsadmserver(1M) command.

    2. # /usr/sbin/mpsadmserver sync-cds 5.2

    Notice the final 5.2. The configuration directory server must be available for this step to complete properly.

  2. Stop all running servers in the following order:
    1. Calendar Server
    2. Messaging Server
    3. Directory Proxy Server
    4. Directory Server
    5. Administration Server
  3. Back out server patches in the same order as for Step 2 using the patchrm(1M) command. Patches applied for each of these servers must be removed.
    1. Calendar Server; (follow product specific instructions in To Remove Calendar Server Patches)
    2. Messaging Server (follow product specific instructions in To Remove Messaging Server Patches)
    3. Directory Proxy Server: (follow product specific instructions in To Remove Directory Proxy Server Patches)
    4. Directory Server: (follow product specific instructions in To Remove Directory Server Patches)
    5. Administration Server: (follow product specific instructions in To Remove Administration Server Patches)
  4. Restart the servers in the following order:
    1. Administration Server
    2. Directory Server
    3. Directory Proxy Server

      4. Note

      To restart the Directory Server that shipped with Java Enterprise System enter:

      directoryserver -d 5.2 start

    4. Messaging Server
    5. Calendar Server
    To Troubleshoot Administration Server

Application Server Upgrade Information

You upgrade Application Server by applying patches, and synchronizing settings with the configuration directory server. This section contains the following:

For information about upgrading web container software, refer to the following web container documentation:

To upgrade from Application Server 7, Update 1 to Application Server 7, Update 3, follow these steps:

    To Upgrade Supplemental Files
  1. Acquire and load the Supplementary files for upgrading Sun Java Enterprise System from 2003Q4 to 2004Q2 for Application Server and Message Queue (see To Upgrade Supplemental Files)
  2. Follow the instructions in the README file to install these Supplementary files.
    To Apply Application Server Patches

Note

Message Queue must be upgraded prior to upgrading Application Server 7, Update 1 (see Message Queue Upgrade Information).

  1. Log in as or become superuser (root).
  2. Stop all running instances of the Application Server by entering:

    3. app_svr_base/bin/ asadmin stop-appserv

  3. Upgrade all Java Enterprise System shared components (see Upgrading Shared Components.)
  4. Apply the following Application Server patches using patchadd(1M):

    5. Table 8-5  Application Server Patches

    Functional Area to Patch

    Patch ID Solaris SPARC

    Patch ID Solaris x86

    Sun One Application Server Unbundled Core Patch

    116286-10

    116287-10

    Application Server 7: Proxy Plugin patch

    116292-10

    116293-10

    Application Server 7: Unbundled Languages Patch

    116354-06

    116355-06

    Note

    Only apply Application Server 7 Proxy Plugin patch (116292 - sparc and 116293 -x86) on the system when the SUNWaspx package is installed. To check for the presence of the SUNWaspx use the command pkginfo -l SUNWaspx.

  5. Restart the Application Server instances.
    To Remove Application Server Patches

If you decide to remove the Application Server patches, perform the following steps:

  1. Stop all running instances of the Application Server by entering:

    2. /asadmin stop-appserv/

  2. Become root:

    3. su root

    When prompted, type your root password.

  3. Remove the appropriate Application Server patches added in To Apply Application Server Patches using patchrm(1M).
  4. Restart the Application Server instances:

    5. app_svr_base/bin/asadmin start-appserv

Calendar Server Upgrade Information

Upgrading Calendar Server involves backing up data, upgrading other Java Enterprise System components and applying the appropriate patches. This section includes:

    To Upgrade Non-Cluster Deployments
  1. Log in as or become superuser (root).
  2. Stop the Calendar Server:

    3. cal_svr_base/cal/sbin/stop-cal

  3. Backup Calendar Server database, configuration file (ics.conf) and other files you have customized. This includes files in the database, configuration and UI xsl and html files.

    4. Default locations for these directories are:

    • Database directory: /var/opt/SUNWics5/csdb
    • Configuration directory: /etc/opt/SUNWics5/config
    • UI XSL and html files: /opt/SUNWics5/cal/html
    • SSL Certificate Directory (if configured): /opt/SUNWics5/cal/lib/alias
  4. Upgrade all the Java Enterprise System components on the server where you are upgrading Calendar Server. Calendar Server relies on:
  5. Apply the following Calendar Server patches using patchadd(1M).

    6. Table 8-6  Calendar Server Patches

    Functional Area to Patch

    Patch ID Solaris SPARC

    Patch ID Solaris x86

    Calendar Server core

    116577-09

    116578-09

    Localization patch

    117010-08

    117011-08

  6. Start the Calendar Server:

    7. cal_svr_base/cal/sbin/start-cal

    Note

    Communications Express is a new web client introduced in Java Enterprise System 2004Q2 Release. You can use the Java Enterprise System installer to install Communications Express after upgrading Calendar Server.

    To Upgrade Cluster Deployments
  1. Stop the cluster services:

    2. cal_svr_base/cal/sbin/stop-cal

  2. To find Cluster nodes containing Calendar Server enter the following:

    3. # pkginfo | grep -i sunwics5

  3. Follow the procedure in To Upgrade Non-Cluster Deployments on each node where the Calendar Server is installed.
    To Upgrade the User Management Utility

Calendar Server requires that you use the User Management Utility (commadmin) to provision users, groups, domains, and resources.

After you apply the patch to upgrade the User Management Utility (see Upgrading Shared Components), you must take the steps described in To Upgrade the User Management Utility and To Use commadmin with Schema 2 Compatibility Mode.

    To Remove Calendar Server Patches

If you decide to remove the Java Enterprise System 2004Q2 patches (116577-09/117010-08 and 116578-09/117011-08), perform the following steps:

  1. Stop the Calendar Server:

    2. cal_svr_base/cal/sbin/stop-cal

  2. Backup the calendar database. The default database directory is:

    3. /var/opt/SUNWics5/csdb

  3. Remove the appropriate Calendar Server Patches added in Step 5.

    4. Remove the shared component patches installed in Step 4 in this order:

  4. Replace SSL certificates from the backup created in Step 3.
  5. To activate the database backed up in Step 3:
    1. Changed directories to:

      2.   cd /var/opt/SUNWics5/csdb

    2. Remove the database temporary files:

      3.   rm __db.*

    3. Remove the database log files:

      4.   rm log.*

    4. Configure Calendar Server by running the Calendar Server configuration program, /opt/SUNWics5/cal/sbin/csconfigurator.sh.

Directory Server Upgrade Information

You upgrade Directory Server by applying patches, and synchronizing settings with the configuration directory server.

    To Apply Directory Server Patches
  1. Follow the instructions for applying patches in Administration Server Upgrade Information. Instructions are also included in the Administration Server patch README file.

    2. Note

    You must follow these instructions and apply Administration Server patches even if you have never explicitly selected Administration Server for installation.

    You may obtain patches from http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access.

  2. If Directory Server is configured, synchronize the upgraded Directory Server settings with those stored in the configuration directory server using the directoryserver(1M) command.

    3. # /usr/sbin/directoryserver -u 5.2 sync-cds

    The configuration directory server must be available for this step to complete properly.

    To Correct the Schema
  1. Remove the nsSchemaCSN attribute from 99user.ldif and 60iplanet-calendar.ldif files.
  2. Rename the schema_push.pl script of the ldap instance (under server_root/slapd-instance) to schema_push.pl.ref.
  3. Copy the template file, i-e template-schema_push.pl, located in server_root/bin/slapd/admin/scripts to server_root/slapd-instance and rename it into schema_push.pl.
  4. Edit the new schema_push.pl file:
    1. Replace {{PERL-EXEC}} with #!/server_root/bin/slapd/admin/bin/perl.
    2. Replace {{MY-DS-ROOT}} with server_root/slapd-instance.
    3. Replace {{SEP}} with "/".
  5. Change the mode of the schema_push.pl to add the execute mode
  6. Force the schema replication by running:

    7. server_root/schema_push.pl.

  7. To verify that the file is correct check that the nsSchemaCSN attribute has been added to 99user.ldif file
    To Upgrade Cluster Configurations

Use the following procedures to apply and, if necessary, to remove patches when running Directory Server as a data service in a cluster.

Note

When applying or backing out patches for Directory Server running as a Sun Cluster data service, you must stop the service for the duration of the update or back out operation because earlier versions of Directory Server 5.2 binaries cannot run on an upgraded Directory Server instance. In other words, the service becomes and remains unavailable during the update.

Back up your data prior to upgrading.

All nodes of the cluster should run the same version/release of Directory Server and the associated Administration Server. All nodes should be patched in sequence, as described in these procedures.

Start patching one node of the cluster, then another node, then another node, and so on until all nodes are upgraded. This is done sequentially, not in parallel. Start patching a new node when done with the previous node.

  1. Stop each Directory Server instance and the associated Administration Server. For example, with one instance:

    2. /usr/sbin/directoryserver stop
    /usr/sbin/directoryserver stop-admin

  2. Make the current cluster node the active node by entering:

    3. scswitch -z -g ldap-group -h this-node-name

  3. Apply the upgrade patches on this node as described in To Apply Directory Server Patches.

    4. Here, patches are located in /var/spool/patch, /export/backout is where backout data is stored, and patch-nbr-list is a whitespace separated list of patch numbers. Java Enterprise System is stopped while patches are applied.

  4. Make another cluster node the active node:

    5. scswitch -z -g ldap-group -h another-node-name

  5. Repeat Step 3 and Step 4 until all nodes in the cluster are patched.
  6. Restart each Directory Server instance and the associated Administration Server. For example, with one instance:

    7. /usr/sbin/directoryserver -u 5.2 start
    /usr/sbin/directoryserver start-admin

  7. If Directory Server is configured, synchronize the updated Directory Server with the configuration directory server using directoryserver(1M). Enter the following on the active node only:

    8. /usr/sbin/directoryserver -u 5.2 sync-cds
    /usr/sbin/mpsadmserver sync-cds

    If the configuration directory server is not on the local system, it must be available for this step to complete properly.

  8. If you want to upgrade from HAStorage to HAStoragePlus, See Upgrading From HAStorage to HAStoragePlus
    To Remove Directory Server Patches
  1. If Directory Server is configured, return to the pre-patch settings stored in the configuration directory using the directoryserver(1M) command.

    2. # /usr/sbin/directoryserver -u 5.2 sync-cds 5.2

    Notice the final 5.2. The configuration directory server must be available for this step to complete properly.

  2. Follow the instructions for removing patches in To Remove Administration Server Patches. Instructions are also included in the Administration Server patch README file.
  3. Make sure the directoryserver(1M) command applies to 5.2 by default:

    4. # /usr/sbin/directoryserver -d 5.2

    To Troubleshoot Directory Server

Upgrading From HAStorage to HAStoragePlus

When running Directory Server as a Sun Cluster data service you might wish to upgrade to HAStoragePlus. This section contains the following topics:

The SUNW.HAStoragePlus resource type synchronizes actions between HA storage and data services, making locally mounted file systems highly available within a cluster. This feature permits higher performance when a disk-intensive data service such as Directory Server undergoes fail over, because the file system access fails over with the service.

Why Use HAStoragePlus

HAStoragePlus can be used with any file system residing in a global device group, but it also provides failover file service in addition to the global file service. Unlike a globally mounted file service, failover file service allows access from only one cluster node at any point in time. It also allows access only from nodes physically connected to the underlying storage device. As with a global file service, when Directory Server switches or fails over from an old node to a new one, HAStoragePlus ensures the file system is unmounted from the old node and remounted on the new node. HAStoragePlus with the failover file service also bypasses the global file system service layer completely, allowing higher performance. It can also work with any file system type supported by the operating system, including types not supported by the global file system service.

Refer to SUNW.HAStoragePlus(5) for background information, and to the Sun Cluster 3.1 4/04 product documentation at http://docs.sun.com/coll/1124.1 for further instructions on setting up a SUNW.HAStoragePlus resource type for new resources.

Performing the Upgrade

This section explains how to upgrade if you have used Directory Server with SUNW.HAStorage and now want to benefit from SUNW.HAStoragePlus. The steps described here replace use of a global file system service with that of a failover file system service. In summary, you modify /etc/vfstab and change the cluster configuration such that the server resource groups depend on HAStoragePlus.

The following procedures reference a ds-resource-group containing a logical hostname resource (lhn-res), a Directory Server resource (ds-res), an Administration Server resource (as-res), and a HAStorage resource (has-res) managing the global file system service. Upon completion, the HAStorage resource is replaced by a HAStoragePlus resource (hasp-res) managing the failover file system service Directory Server uses. Perform all procedures listed below in order to enable HAStoragePlus.

    To Disable Dependencies on the HAStorage Resource
  1. Take the Directory Server resource group off line.

    2. # scswitch -F -g ds-resource-group

  2. Disable and remove the Directory Server resource from the resource group.

    3. # scswitch -n -j ds-res
    # scswitch -r -j ds-res

  3. Disable and remove the Administration Server resource from the resource group.

    4. # scswitch -n -j as-res
    # scswitch -r -j as-res

  4. Disable and remove the HAStorage resource from the resource group.

    5. # scswitch -n -j has-res
    # scswitch -r -j has-res

    To Update the File System Configuration
  1. Unmount the file system.
  2. Edit /etc/vfstab to:
    • Remove the global flag for the file system, defining it as a local file system.
    • Make sure the logging option is set for the file system.
    • Unset the option to mount at boot.

Do not mount the file system at this point. Proceed to To Prepare the HAStoragePlus Resource.

    To Prepare the HAStoragePlus Resource
  1. Register and add the HAStoragePlus resource to the resource group.

    2. # scrgadm -a -t SUNW.HAStoragePlus
    # scrgadm -a -j hasp-res -g ds-resource-group -t SUNW.HAStoragePlus \
    -x FilesystemMountPoints=volume-mount-point

    Here volume-mount-point identifies the disk volume where Directory Server stores data.

  2. Enable the HAStoragePlus resource.

    3. # scswitch -e -j hasp-res

    To Enable Dependencies on the HAStoragePlus Resource
  1. Bring the Directory Server resource group on line.

    2. # scswitch -Z -g ds-resource-group

  2. Recreate the Directory Server resource with a dependency on hasp-res.

    3. # scrgadm -a -j ds-res -g ds-resource-group -t SUNW.dsldap \
    -y Network_resources_used=logical-host-name \
    -y Port_list=port-number/tcp \
    -x Confdir_list=ServerRoot/slapd-serverID \
    -y Resource_dependencies=hasp-res

  3. Enable the Directory Server resource.

    4. # scswitch -e -j ds-res

  4. Recreate the Administration Server resource with a dependency on hasp-res.

    5. # scrgadm -a -j as-res -g ds-resource-group -t SUNW.mps \
    -y Network_resources_used=logical-host-name \
    -y Port_list=port-number/tcp \
    -x Confdir_list=ServerRoot \
    -y Resource_dependencies=hasp-res

  5. Enable the Administration Server resource.

    6. # scswitch -e -j as-res

At this point, the servers use HAStoragePlus which mounts and unmounts the file system as necessary.

Directory Proxy Server Upgrade Information

You upgrade Directory Proxy Server by applying patches, and synchronizing settings with the configuration directory server.

This section describes preparation and a procedure for updating Directory Proxy Server 5.2 to Directory Proxy Server 5 2004Q2. It contains:

    To Apply Directory Proxy Server Patches
  1. Follow the instructions for applying patches in Administration Server Upgrade Information. Instructions are also included in the Administration Server patch README file.

    2. Note

    You must follow these instructions and apply Administration Server patches even if you have never explicitly selected Administration Server for installation.

    Ensure Configuration Directory Server is running.

    You may obtain patches from http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access.

  2. If Directory Proxy Server is configured and did not synchronize settings with the configuration server when patches are applied, manually synchronize upgraded Directory Proxy Server settings with those stored in the configuration directory server.

    3. # AS_BASEDIR/usr/sadm/mps/admin/v5.2/bin/tcl8.2/tclsh
    # AS_BASEDIR/usr/sadm/mps/admin/v5.2/bin/bin/dps/install/script/sync-dps-cds.tcl \
    -cid AS_BASEDIR/usr/sadm/mps/admin/v5.2 -serverroot ServerRoot

    Where:

    • AS_BASEDIR is / by default, and thus may be left out.
    • The -cid option takes a full path, cid_path, such that the program can assert that the following directory exists:

      • cid_path/bin/dps/install/script

    • The -serverroot option takes the full path to an installed and configured Administration Server. The script validates that the following files exist:

      • ServerRoot/admin-serv/config/adm.conf

      ServerRoot/admin-serv/config/jvm12.conf

      The configuration directory server must be available for this step to complete properly.

    To Remove Directory Proxy Server Patches
  1. If Directory Proxy Server is configured, return to the pre-patch settings stored in the configuration directory.

    2. # AS_BASEDIR/usr/sadm/mps/admin/v5.2/bin/tcl8.2/tclsh
    # AS_BASEDIR/usr/sadm/mps/admin/v5.2/bin/bin/dps/install/script/sync-dps-cds.tcl \
    -cid AS_BASEDIR/usr/sadm/mps/admin/v5.2 -serverroot ServerRoot -v5.2

    Notice the trailing -v5.2 option. Where:

    • AS_BASEDIR is / by default, and thus may be left out.
    • The -cid option takes a full path, cid_path, such that the program can assert that the following directory exists:

      • cid_path/bin/dps/install/script

    • The -serverroot option takes the full path to an installed and configured Administration Server. The script validates that the following files exist:

      • ServerRoot/admin-serv/config/adm.conf

      ServerRoot/admin-serv/config/jvm12.conf

      The configuration directory server must be available for this step to complete properly.

  2. Follow the instructions for removing patches included in the Administration Server patch README file.
    To Troubleshoot Directory Proxy Server
  1. After upgrading to Directory Proxy Server 5 2004Q2, starting the console.

    2. You should see the console shown in Figure 8-1.

    Figure 8-1  Directory Proxy Server Console
    The latest console shows Sun Java System branding.

  2. If after applying the patches, you still see a Sun ONE-branded console, rather than a console with the Sun Java System brand, verify that you effectively synchronized with the configuration directory server.

    3. If backing out the patches did not work, typically this is because you did not synchronize settings for the upgraded Directory Proxy Server with the configuration directory server before you tried to back out patches.

  3. Try the entire process again, starting from To Apply Directory Proxy Server Patches.

Identity Server Upgrade Information

This section includes the following information about upgrading an instance of Identity Server 6.1:

Backing up Web Container Customized Files

Before you upgrade, back up any web container customized files related to Identity Server 6.1, including:

It is recommend that you make a list of your customized configuration so you can redo them after you upgrade and then verify that they work correctly.

You must provide the same encryption key used when installing Identity Server 6.1. This key is located in the am.encryption.pwd property in the file:

id_svr_base/lib/AMConfig.properties

Note

AMConfig.properties is moved by the pre-upgrade script to a location of your choice and renamed with a .bak extension. The default encryption key generated and presented during upgrade will not work.

Refer to the following for additional details prior to upgrading Identity Server:

Upgrading Web Container Software

Identity Server 6 2004Q2 supports Web Server 6.1 SP 2 or Application Server 7 Update 3 as a web container. If you are using an older version, you must upgrade the web container software before you can upgrade to Identity Server 6 2004Q2.

For information about upgrading web container software, refer to the respective web container documentation:

Also, if you saved any customization files under Backing up Web Container Customized Files, you will need to redo the customizations after you upgrade the web container.

Note

If the web container used is Application Server, verify the Application Server is running.

    To Verify That the Application Server Instance is Running
  1. Change directory to the Application Server installation directory (default is /opt/SUNWappserver7) and enter the following:

    2. cd /opt/SUNWappserver7

    asadmin list-instances

    asadmin>list-instances
    admin-server <running>
    server1 <running>
    asadmin>

    If a non-default instance was used then output will be different.

  2. If necessary, start the Application Server instance domain:

    3. cd /opt/SUNWappserver7/bin

    asadmin> start-domain --domain domain-name

    asadmin>start-domain --domain domain-name
    Instance domain-name:admin-server started
    Instance domain-name:server1 started
    Domain domain-name Started.

    Use the appropriate domain name. This defaults to domain1 unless otherwise changed.

  3. To see all available domains enter:

    4. asadmin> list-domains

    domain1 [/var/opt/SUNWappserver7/domains/domain1]
    asadmin>

Running the Pre-Upgrade Script

The Identity Server 6 2004Q2 pre-upgrade script (pre61to62upgrade) is part of the Sun Java Enterprise System and is available in the following directory:

JavaEnterpriseSystem_base/Solaris_sparc/Product/identity_srv/Tools

where JavaEnterpriseSystem_base is the directory where you uncompressed the archive.

The pre-upgrade script performs these functions:

Before executing the pre-upgrade script, the following servers must be running:

    To Run the Pre-Upgrade Script
  1. Log in as or become superuser (root).
  2. Verify that Directory Server is running. For example:

    3. # ps -ef | grep slapd

    If Directory Server is not running, start it. For example:

    # cd /var/opt/mps/serverroot/slapd-instance-name
    # ./start-slapd

  3. Move to the directory where the pre-upgrade script exists and then run the script. For example:

    4. # cd JavaEnterpriseSystem_base/Solaris_sparc/Product/identity_srv/Tools
    # ./pre61to62upgrade

  4. When you are prompted by the script, enter the following information:
    • Directory Server fully qualified host name. For example: ds.example.com
    • Directory Server port number. Default is 389.
    • Distinguished name (DN) and password of the top-level Identity Server administrator. For example: uid=amAdmin,ou=People,dc=example,dc=com
    • Directory where the script should back up the Identity Server 6.1 files. For example: /opt/is_backup
    • Certificate directory of the web container. For example: /opt/SUNWwbsvr/alias

The pre-upgrade script displays its status as it runs. Be sure to allow the script to finish completely. If you stop the script before it has finished, the results will be unpredictable.

After the script finishes, you are ready to install Identity Server 6 2004Q2.

Installing Identity Server

To install Identity Server 6 2004Q2, you must run the Sun Java Enterprise System installer.

Before you run the installer, use the Identity Server Worksheets to record necessary information. Also, when the installer asks “Is Directory Server provisioned with user data?”, answer “yes”.

Note

The Web Server detail screen (menu 3 of 6) appears with the correct information. However, when you press the next button, an error message is displayed stating that the Web Server directory as listed is not valid. Use the browse feature to select the same location and then proceed.This is only applicable to the web server container.

Select the New Console option rather than the Use Existing Console option. (menu 4of 6)

Answer yes when the installer asks Is Directory Server provisioned with user data? (menu 6 of 6).

Running the Post-Upgrade Script

The Identity Server post-upgrade script (Upgrade61DitTo62) is available in the following directory after you install Identity Server 6 2004Q2:

/IdentityServer_base/SUNWam/migration/61to62/scripts

where IdentityServer_base is the Identity Server 6 2004Q2 base installation directory. The default base installation directory is /opt.

The post-upgrade script performs these functions:

To run the post-upgrade script, Directory Server must be running. During the script, you will be asked to restart Directory Server before the script can continue. At the end, you will also be asked to restart both Directory Server and the web container for the changes to take effect.

    To Run the Identity Server Post-Upgrade Script
  1. Log in as or become superuser (root).
  2. Verify that Directory Server is running. For example:

    3. # ps -ef | grep slapd

    If Directory Server is not running, start it. For example:

    cd /var/opt/mps/serverroot/slapd-instance-name
    ./start-slapd

  3. Run the post-upgrade script. For example:

    4. cd /IdentityServer_base/SUNWam/migration/61to62/scripts
    ./Upgrade61DitTo62

    where IdentityServer_base is the Identity Server 6 2004Q2 base installation directory.

    Note

    If the script fails with an object class violation perform the procedures at To Correct the Schema and restart the Directory Server.

  4. When you are prompted by the script, provide the following information:
    • Directory Server fully qualified host name–For example: ds.example.com
    • Directory Server port number–Default is 389.
    • Distinguished name (DN) and password of the Directory Manager
    • Distinguished name (DN) and password of the top-level Identity Server administrator–For example: uid=amAdmin,ou=People,dc=example,dc=com
  5. When you are prompted by the script, restart Directory Server. The script pauses for you to perform the restart.
  6. After you restart Directory Server, return to the script and press Enter to continue. After the script has finished, it displays the following message:

    7. YOU MUST RESTART THE DIRECTORY AND WEB SERVERS FOR THE UPGRADE CHANGES TO TAKE EFFECT.

  7. Restart Directory Server and the web container.

After Directory Server and the web container are running, you are ready to verify that the upgrade was successful.

Verifying the Upgrade

If you customized your Identity Server 6.1 installation, you must manually redo the customizations in your new Identity Server 6 2004Q2 installation.

Here are several ways to verify that the upgrade was successful:

Upgrading Multiple Instances of Identity Server

This section describes how to upgrade multiple instances of Identity Server 6.1 running on different hosts that share the same Directory Server.

Identity Server 6.1 and Identity Server 6 2004Q2 servers installed on different hosts can run concurrently against the same shared Directory Server.

    To Upgrade Multiple Instances of Identity Server
  1. Log in as or become superuser (root).
  2. Stop all Identity Server 6.1 instances that access the Directory Server. For example:

    3. # cd /IdentityServer_base/SUNWam/bin
    # ./amserver stop

    where IdentityServer_base is the Identity Server 6.1 base installation directory.

    Stopping all instances prevents Identity Server from making changes to the Directory Server while you are performing the upgrade.

  3. Start the instance you want to upgrade. For example:

    4. # ./amserver start

  4. Upgrade the Identity Server instance you started in Step 3. See:
  5. Restart the instance you just upgraded.

    6. Repeat Step 3 through Step 5 for each Identity Server 6.1 instance on a different host that you want to upgrade.

  6. If there are any Identity Server 6.1 instances you did not upgrade, restart those instances. For information about the co-existence of Identity Server 6.1 and Identity Server 6 2004Q2 see the Sun Java System Identity Server 2004Q2 Migration Guide at http://docs.sun.com/doc/817-5708.

    7. Note

    The upgrade process supports multiple instances of Identity Server installed on different host systems. Upgrading multiple instances of Identity Server installed on the same host is not supported in the current release. If you have multiple instances on the same host, after you upgrade the main instance, you must then recreate the additional instances.

    To Use Portal Server Mobile Access

To use Java System Portal Server, Mobile Access 6 2004Q2, change the Identity Server Client Detection global attributes as follows:

  1. Access the Identity Server 6 2004Q2 console using the following URL:

    2. http://host-name.domain-name:port/amconsole

    where host-name.domain-name:port is the fully qualified host name and port of the web container you are using.

  2. When the Identity Server login page appears, log in as amadmin.
  3. On the console, click the Service Configuration tab.

    4. The console displays the Service Configuration options in the navigation frame.

  4. In the navigation frame under Service Configuration, click Client Detection.
  5. For Client Detection, set the following items in the data frame:
    1. Set the Client Detection Class global attribute to com.sun.mobile.cdm.FEDIClientDetector
    2. Click the Enable Client Detection check box.
  6. Click Save.
    To Upgrade the Identity Server SDK Only

To upgrade an Identity Server 2003Q4 (6.1) SDK only installation, you must uninstall the 2003Q4 version and then re-install the 2004Q2 version. To upgrade an Identity Server SDK only installation:

  1. Back up your Identity Server 2003Q4 configuration files, including the AMConfig.properties and serverconfig.xml files. (The upgrade process will not affect your user data.)
  2. Uninstall the Identity Server 2003Q4 SDK by following the instructions in Chapter 10, "Uninstalling Software."
  3. Install the Identity Server 2004Q2 SDK by following the instructions in Installing Software Using the Graphical Interface.
  4. Incorporate the configuration changes you saved in Step 1 into the new Identity Server 2004Q2 configuration files.

Instant Messaging Upgrade Information

You upgrade Instant Messaging by applying patches, and synchronizing settings with the configuration directory server.

This section includes the following information about upgrading an instance of Instant Messaging:

    To Apply Instant Messaging Patches
  1. Log in as or become superuser (root).
  2. Stop the Instant Messaging service (if the server component is installed) by entering:

    3. inst_msg_base/sbin/imadmin stop

  3. Backup files data files, configuration, and customized client files.

    4. Default locations for these directories are as follows:

    Table 8-7  Data Locations

    Type

    Location

    Configuration

    /etc/opt/SUNWiim/

    Messenger resources

    imdocroot (default /opt/SUNWiim/html)

    User data

    See iim.instancevardir configuration option for exact location. (default is /var/opt/SUNWiim/default/db).

  4. Apply following Instant Messaging patches using patchadd(1M):

    5. Table 8-8  Instant Messaging Patches

    Functional Area to Patch

    Patch ID Solaris SPARC

    Patch ID Solaris x86

    Instant Messaging core

    115732-09

    116645-09

    Localization

    116936-06

    116937-06

  5. Restart the Instant Messaging service (if the server component is installed).
    To Remove Instant Messaging Patches

If you decide to remove the Instant Messaging patches, perform the following steps:

  1. Stop Instant Messaging.
  2. Backup files data files, configuration, and customized client files.

    3. Default locations for these directories are as follows:

    Table 8-9  Data Locations

    Type

    Location

    Configuration

    /etc/opt/SUNWiim/

    Messenger resources

    imdocroot (default /opt/SUNWiim/html)

    User data

    See iim.instancevardir configuration option for exact location. (default is /var/opt/SUNWiim/default/db).

  3. Become root:

    4. su root

    When prompted, type your root password.

  4. Remove the appropriate Instant Messaging patches added in Step 4 using patchrm(1M).

Message Queue Upgrade Information

This section contains procedures for upgrading to Message Queue 3.5 SP1 from the previous version. It contains the following topics:

    To Upgrade Supplemental Files
  1. Acquire and load the Supplementary files for upgrading Sun Java Enterprise System from 2003Q4 to 2004Q2 for Application Server and Message Queue (see To Upgrade Supplemental Files)
  2. Follow the instructions in the README file to install these Supplementary files.
    To Upgrade Message Queue on Solaris

You do not need to uninstall the previous version—it will be over-written. The following instructions explain how to install the Message Queue product on Solaris.

  1. Obtain the software either via product distribution download or off the CD.
  2. Log in as or become superuser (root).
  3. Shut down any existing Message Queue brokers by entering:

    4. imqcmd shutdown bkr -u name -p password [-b hostName:port]

  4. To upgrade the Message Queue shipped with Java Enterprise System 2003Q4 to the Message Queue shipped with Java Enterprise System 2004Q2, run the mqupgrade script:

    5. # cd /cdrom/cdrom0/Solaris_arch/Product/message_queue/Tools
    # ./mqupgrade

    The above example finds the command on the product CD. to execute the command from your download location:

    # cd /unzipped location/Solaris_arch/Product/message_queue/Tools
    # ./mqupgrade

    Note

    mqupgrade will first ask if you want to install any shared components first. If you have not already upgraded shared components answer y. If you have already upgraded shared components answer n.

    The script creates a log file in the following directory:

    /var/sadm/install/logs/Message_Queue_upgrade_date.log

    Note

    Message Queue upgrade preserves all configuration data and any state maintained by the Message Queue brokers.

  5. Exit the root shell.
    To Check the Message Queue Installation

To check that the expected version of Message Queue is running on your system, enter the command:

imqbrokerd -version

The output to this command specifies the version of the JDK and Message Queue that are installed on your system.

Messaging Server Upgrade Information

This section contains procedures for upgrading to Messaging Server 6 2004Q2 from the previous Java Enterprise System 2003Q4 version. It contains the following topics:

Prerequisites

Prior to performing the Messaging Server 6 2004Q2 upgrade ensure that the following steps are taken:

  1. Stop the Messaging Server.
  2. Upgrade all Java Enterprise System components on the server where you are upgrading Messaging Server. In particular, the Java Enterprise System components that Messaging Server may rely on. The list includes:
    • Shared components, in particular: NSPR (SUNWpr), NSS (SUNWtls), SASL (SUNWsasl), ICU (SUNWicu), LDAPCSDK (SUNWldk), and JSS (SUNWjss) (see Upgrading Shared Components)
    • Administration Server (see Administration Server Upgrade Information)
    • Directory Server (see Directory Server Upgrade Information)
    • Identity Server (see Identity Server Upgrade Information)
    • Web Server (see Web Server Upgrade Information)
    • Application Server (see Application Server Upgrade Information)
    • Communications Services User Management Utility (this is upgraded with Upgrading Shared Components and configured in To Upgrade the User Management Utility)

      • Note

      All the above components may not be present on the machine. Also note that Messaging Server may not be using all the above components, even though they are present. Upgrade the above components to the Java Enterprise System 2004Q2 versions.

      Messaging Server relies on Communication Services User Management Utility, if present, which in turn relies on Identity Server. Identity Server relies on a web container. Among the choices for Identity Server is Application Server and Web Server.

      Messaging Server may rely on Web Server if the user chooses to deploy the mail filters and/or deploy the new Sun ONE Unified Web Client that comes in Java Enterprise System 2004 Q2.

      You must follow these instructions and apply Administration Server patches even if you have never explicitly selected Administration Server for installation.

      Messaging Server cannot start in secure mode when you back out patches after having changed the server certificate. You can, however, turn off secure mode, restart Messaging Server, reinstall the server certificate, and then enable SSL mode.

    To Upgrade Non-Cluster Deployments
  1. Log in as or become superuser (root).
  2. Apply the Messaging Server patches using patchadd(1M). The three patches are listed below.

    3. Table 8-10  Messaging Server Patches 

    Functional Area to Patch

    Patch ID Solaris SPARC

    Patch ID Solaris x86

    Messaging Server core

    116568-51

    116569-51

    Localization

    116570-09

    116571-09

    vcsha (Optional, only for Veritas HA installations)

    116574-01

     

  3. Generate the new candidate configuration files using the following program:

    4. msg_svr_base/sbin/patch-config

  4. Apply the new configuration files, either manually or using the following program:

    5. msg_svr_base/sbin/install-newconfig

  5. Apply the ldif files under msg_svr_base/lib/patch. Be sure to use the ldapmodify command that comes with the Messaging Server or Directory Server.
  6. Execute the following command to create a compile configuration if desired:

    7. msg_svr_base/sbin/imsimta chbuild

    msg_svr_base/sbin/imsimta clbuild -image_file=IMTA_COMMAND_DATA IMTA_BIN:pmdf.cld

    msg_svr_base/sbin/imsimta cnbuild

  7. Start the Messaging Server with:

    8. msg_svr_base/sbin/start-msg

    To Upgrade Cluster Deployments

If you have two or more instances of Messaging Server in a clustered environment, use a rolling upgrade strategy, one server at a time, to keep most of the cluster available. First you upgrade one Messaging Server on one machine. The Messaging Server upgrade includes upgrading the mboxlist database to a higher version (for that Messaging Server on that machine).

To install in cluster environments:

  1. Install Messaging Server 6 2004Q2 on the standby node.
  2. Configure it to use the configuration data of primary node.
  3. Failover to the standby node.
  4. Remove the primary node from the cluster.
  5. Upgrade the primary node using patchadd (see Step 2.)
  6. Put the primary node back into the cluster.
  7. Failover the configuration and data from the standby node back to the primary node.
  8. Run patch-config to generate new candidate upgraded configuration files.
  9. Examine the new candidate upgraded configuration files manually.
  10. Schedule downtime for the primary node configuration and data.

    11. During downtime:

    1. Stop the services for the primary node.
    2. Install the new confide files, e.g. you can use the install-unconfined command.
    3. Run the commands.

      4. msg_svr_base/sbin/imsimta chbuild

      msg_svr_base/sbin/imsimta clbuild -image_file=IMTA_COMMAND_DATA IMTA_BIN:pmdf.cld

      msg_svr_base/sbin/imsimta cnbuild

    4. Restart the services.
  11. Repeat Step 2 throughStep 10 for every node to be upgraded on the cluster.
    To Upgrade the User Management Utility

Messaging Server and Calendar Server require that you use the User Management Utility (commadmin) to provision users, groups, domains, and resources.

After you apply the patch Sun ONE commcli core to upgrade the User Management Utility (see Upgrading Shared Components), you must take the following manual steps:

  1. Run the User Management Utility configuration program, config-iscli. For instructions on running the config-iscli program, see the Sun Java System Communications Services User Management Utility Administration Guide (http://docs.sun.com/doc/817-5703).
  2. Obtain ACIs to properly restrict the privileges of the domain administrator.

    3. Take the following steps:

    1. Open the usergroup.ldif file, located in the following path:

      2. opt/SUNWcomm/config/usergroup.ldif

    2. Replace ugldapbasedn in the template ldif with your usergroup suffix.
    3. Add the edited usergroup.ldif into the LDAP directory.
  3. Add the commcli.mod.ldif file to the LDAP directory. This file is located in the following path:

    4. opt/SUNWcomm/install/patch/patchnumber-rev_number/commcli.mod.ldif

    where patchnumber-rev_number is the number and latest revision number of the patch.

    To Use commadmin with Schema 2 Compatibility Mode

To enable the User Management Utility (commadmin) to work on an LDAP directory in Schema 2 compatibility mode, you must take additional manual steps, summarized below.

  1. For detailed instructions in how to carry out these steps, see “User Management Utility” in the “Known Issues and Limitations” section of the Sun Java System Messaging Server Release Notes (http://docs.sun.com/doc/817-6363).

    2. Summary of manual steps:

    1. Apply several ACIs to the Organization Tree root suffix and DC Tree root suffix.
    2. Set the com.iplanet.am.domaincomponent property in the AMConfig.properties file to your DC Tree root suffix.
    3. Enable Identity Server to use compatibility mode by opening the Identity Server Console and checking the Domain Component Tree Enabled check box.
    4. Add the inetdomain object class to all DC Tree nodes in your directory.
    5. Restart the Web container.
    To Remove Messaging Server Patches
  1. Stop the Messaging Server with the stop-msg command.
  2. Disable the watcher daemon by running the configutil command, as follows:

    3. configutil -o local.watcher.enable -v no

  3. Remove the message store database environment files by using the stored -r command.

    4. If this command fails to remove the files, use the stored -R command. This action forces the removal of the files.

  4. Enable the watcher daemon as follows:

    5. configutil -o local.watcher.enable -v yes

  5. Remove the log files under the mboxlist directory. For example:

    6. rm -f /var/opt/SUNWmsgsr/store/mboxlist/log.*

  6. Remove the Messaging Server 6 2004Q2 patches by running the patchrm patch id command.
  7. Manually restore the backed-up configuration files as required. Pre-upgrade configuration files are stored under:

    8. msg_svr_base/install/patch/patchnumber/save

    patchnumber is the Messaging Server core patch.

  8. Run the imsimta cnbuild command, as follows:

    9. msg_svr_base/sbin/imsimta cnbuild

  9. Start Messaging Server with the start-msg command, as follows:

    10. msg_svr_base/sbin/start-msg

    To Remove the commadmin Patch

If you need to back out the commadmin patch, apply the commcli.revert.ldif file, located in the following path:

opt/SUNWcomm/install/patch/116585-rev_number/commcli.revert.ldif

where rev_number is the latest revision number of the patch.

Mobile Access Upgrade Information

Mobile Access 6.2 shipped as a point product intended to augment Java Enterprise System 2003Q4 installations of Identity Server and Portal Server. Mobile Access functionality is now a standard feature of Java Enterprise System 2004Q2. Mobile enablement of Identity Server and Portal Server is now standard.

Use this section to migrate from Java Enterprise System 2003Q4, with or without Mobile Access 6.2 installed, to an Java Enterprise System 2004Q2 installation. This section contains:

Migration Scenarios and Strategies

Java Enterprise System 2003Q4 only permitted installation of Identity Server and Portal Server on the same machine, so these comments only apply to that scenario. These instructions do not encompass the notion of creating a separated Identity Server and Portal Server installation as a result of the upgrade from Java Enterprise System 2003Q4 to Java Enterprise System 2004Q2. Separated installations of Identity Server and Portal Server must be approached as clean installs.

Note

Prior to beginning the upgrade process, take care to save all your customized files related to their Mobile Access 6.2 installation (if any).

Migrating Customized Environments

This scenario encompasses those installations for which Identity Server and Portal Server from Java Enterprise System 2003Q4 were installed, and to which was applied an installation of the Mobile Access 6.2 point product.

    To Upgrade Systems With Mobile Access 6.2
  1. Run the Mobile Access 6.2 uninstaller (uninstallmap) in the same base directory as Portal Server (/opt by default). Make sure the “Clean relevant Portal Server information from Identity Server” check box is not checked.
  2. Remove Mobile Access 6.2, by running the uninstaller that was generated when Mobile Access was installed. It is located in the installation directory chosen at install time under /opt. Also, run the following commands to clean the Mobile Access directories and files:
    1. Locate the Tools directory on the CD or Java Enterprise System web page.
    2. Copy the mobileaccess.tar.gz file to a local hard drive.
    3. Unzip and untar the contents of the mobileaccess.tar.gz file to a local directory.

      4. Note

      The GNU versions of the zip and tar commands (gunzip and gtar) should be used.

    4. Run the following command from the local directory:

      5. > ./unconfigureMA62

  3. Upgrade Identity Server (refer to Identity Server Upgrade Information).
  4. Upgrade Portal Server (refer to Portal Server Upgrade Information).
  5. Run Java Enterprise System 2004Q2 Mobile Access updater.
    To Upgrade Systems Without Mobile Access 6.2

This scenario encompasses those installations for which Identity Server and Portal Server from Java Enterprise System 2003Q4 were installed, and to which the Mobile Access 6.2 point product was not applied. These steps must be performed in order that future versions of Java Enterprise System may upgrade Identity Server and Portal Server correctly.

  1. Upgrade Identity Server (refer to Identity Server Upgrade Information).
  2. Upgrade Portal Server (refer to Portal Server Upgrade Information).
  3. Run Java Enterprise System Mobile Access installer.

Differences Between Mobile Access 6.2 and Mobile Access for Java Enterprise System 2004Q2

There are several differences between Mobile Access 6.2 and Mobile Access for Java Enterprise System 2004Q2 that may require manual intervention to properly migrate certain customizations from the old to the new environment.

Configuration Files

Unlike Java Enterprise System 2003Q4, Java Enterprise System 2004Q2 permits the installation of Identity Server and Portal Server on separate machines. While Mobile Access functionality is largely driven by information stored in an LDAP directory, a few features require configuration via standard flat files.

In Java Enterprise System 2003Q4, this configuration information was stored in:

/etc/opt/SUNWps/MAP/MAPConfig.properties

The ability to separate Identity Server and Portal Server installations in Java Enterprise System 2004Q2 requires that this file be re-factored into the following two files

Table 8-11  Identity Server and Configuration Files

File Name

Where Present

/etc/opt/SUNWma/config.properties

Present on all Identity Server and Portal Server installations

/etc/opt/SUNWps/MAConfig.properties

Present on Portal Server installations

No new configuration properties related to Mobile Access have been introduced in Java Enterprise System 2004Q2, but for reference, the properties are now distributed between the two configuration files in the following way:

/etc/opt/SUNWma/config.properties

The properties in this file pertain to mobile enablement common to both Identity Server and Portal Server installations. The properties contained in this file are:

/etc/opt/SUNWps/MAConfig.properties

The properties in this file pertain to mobile enablement within Portal Server installations. The properties contained in this file are:

Portal Desktop Types

Mobile Access 6.2 added two additional desktop types: “MAP” and “sampleMAP”. These desktop types were reflected in the following file hierarchies:

/etc/opt/SUNWps/desktop/MAP

/etc/opt/SUNWps/desktop/sampleMAP

Portal Server Mobile Access for Java Enterprise System 2004Q2 has migrated the “MAP” desktop into the “default” desktop and has migrated the “sampleMAP” desktop into the “sampleportal” desktop and has eliminated the “MAP” and “sampleMAP” desktop types.

If you have customized either the “MAP” or “sampleMAP” desktops you will need to migrate those changes into the new Java Enterprise System 2004Q2 “default” and “sampleportal” desktops.

If you have defined their own desktop types you will need to add the custom desktop types back via the Identity Server administration console, following a Java Enterprise System 2003Q4 to Java Enterprise System 2004Q2 upgrade.

Client Data

Mobile Access 6.2 and Mobile Access for Java Enterprise System 2004Q2 implement different directory schemas for the storage of client data.

The upgrade process removes the Java Enterprise System 2003Q4 client data from the directory and replaces it with an updated set of client data. Prior to upgrading to Java Enterprise System 2004Q2, customers who have defined their own client data or have modified existing client data should make note of those additions or modifications and be prepared to re-apply them via the Identity Server console following the Java Enterprise System 2004Q2 upgrade.

Portal Server Upgrade Information

This section contains procedures for upgrading to Portal Server 2004Q2 from the previous Java Enterprise System version. It contains the following topics:

Accessing Patches for Upgrading Portal Server

Upgrading Portal Server is done using patches. Download the patches listed in the following table from SunSolve. Use the revisions shown or later.

Table 8-12  Portal Server 2004Q2 Patches

Functional Area to Patch

Patch ID Solaris SPARC

Patch ID for x86

Portal Server

116736-20

116737-20

Secure Remote Access Support

116749-20

116750-20

Gateway

116738-19

116739-19

Rewriter Proxy

116742-19

116743-19

Netlet Proxy

116740-19

116741-19

Localization

117012-05

117105-05

Backing up Web Container Customized Files

Before you upgrade, back up any web container customized files related to Portal Server 6.2, including:

It is recommend that you make a list of your customizations so you can redo them after you upgrade and then verify that they work correctly.

The following directories should be backed up:

Upgrading the Sun Web Container Software

The Java Enterprise System 2004Q2 release requires that the Identity Server instance be run on Sun’s Web Server or Application Server (such as Web Server 6.1 SP2 or Application Server 7 Update 3) on the same system. If you are using an older version, you must upgrade the web container software before you can upgrade to Java Enterprise System 2004Q2 release.

For information about upgrading Sun’s Web Server or Application Server software, refer to the respective web container documentation:

Also, if you saved any customization files under Backing up Web Container Customized Files, you will need to redo the customizations after you upgrade the web container.

Upgrading Identity Server

Portal Server upgrade has a dependency on Identity Server. Prior to upgrading Portal Server, upgrade all systems running Identity Server to the Java Enterprise System 2004Q2 version.

Refer to the Identity Server Upgrade Information for more a more detailed description of the Identity Server upgrade.

    To Enable Client Detection

In order to enable client detection, change the Identity Server Client Detection global attributes as follows:

  1. Access the Identity Server 2004Q2 console using the following URL:

    2. http://host-name.domain-name:port/amconsole

    where host-name.domain-name:port is the fully qualified host name and port of the web container you are using.

  2. When the Identity Server login page appears, log in as amadmin.
  3. On the console, click the Service Configuration tab.

    4. The console displays the Service Configuration options in the navigation frame.

  4. In the navigation frame under Service Configuration, click Client Detection.
  5. Click Save.

Using Third-Party Web Containers

The Java Enterprise System 2004Q2 release only supports WebLogic 8.1 SP2 or WebSphere 5.1 web containers running on a separate system using the Identity Server SDK.

Caution

You must provide the same encryption key used when installing Identity Server 6.1. This key is located in the am.encryption.pwd property in the file:

id_svr_base/lib/AMConfig.properties

The AMConfig.properties is moved by the pre-upgrade script to a location of your choice and renamed with a .bak extension. The default encryption key generated and presented during upgrade will not work.

    To Use Third-Party Web Containers
  1. Uninstall Identity Server 6.1 on the WebLogic 6.1 SP4 or WebSphere 4.0.5 node while preserving the data stored in the configuration Directory Server.
  2. Run the appropriate vendor upgrade script for:
    • WebLogic 6.1 SP4 to WebLogic 8.1 SP2
    • WebSphere 4.0.5 to WebSphere 5.1
  3. Run the Identity Server 2004Q2 pre-upgrade script on the WebLogic 8.1 SP2 or WebSphere 5.1 node.
  4. Install Identity Server, Directory Server, and either Web Server or Application Server on a separate system.

    5. When asked “Is Directory Server provisioned with user data?”, answer yes.

  5. Install the Identity Server SDK on the WebLogic 8.1 SP2 or WebSphere 5.1 node.

    6. When asked “Is Directory Server provisioned with user data?”, answer yes.

  6. Upgrade Portal Server on the WebLogic or WebSphere nodes.

Upgrading Portal Server

This section contains procedures for upgrading Portal Server. It also contains upgrade procedures for products associated with Portal Server. Follow the procedures in the following sections as appropriate:

    To Upgrade Portal Server
  1. Log in as root.

    2. Note

    If Mobile Access 6.2 support was installed on the Java Enterprise System 2003Q4 system, you must remove it prior to upgrading to Portal Server 6 2004Q2.

    Once applied, the Portal Server patches cannot be removed. To see if Mobile Access 6.2 support was installed, enter the following command:

    > /usr/bin/pkginfo -l SUNWpswp

  2. To remove Mobile Access 6.2, run the uninstaller that was generated when Mobile Access was installed. It is located in the installation directory chosen at install time under /opt. Also, run the following commands to clean the Mobile Access directories and files:
    1. Locate the Tools directory on the CD or Java Enterprise System web page.
    2. Copy the mobileaccess.tar.gz file to a local hard drive.
    3. Unzip and untar the contents of the mobileaccess.tar.gz file to a local directory.

      4. Note

      The GNU versions of the zip and tar commands (gunzip and gtar) should be used.

    4. Run the following command from the local directory:

      5. > ./unconfigureMA62

  3. Run the following commands to install the patches:

    4. > patchadd 116736-20
    > patchadd 116749-20

    Patch 116749-20 is needed if Secure Remote Access is installed. Patches 116736-20 and 116749-20 are intended for a Solaris SPARC system (refer to Portal Server 2004Q2 Patches for patch information for a Solaris x86 system).

  4. Run the following commands to upgrade the Portal Server (with /opt/SUNWps as the default installation directory):

    5. > cd /opt/SUNWps/lib
    > ./upgradePS
    > ./upgradeSRA

    The upgradeSRA script is needed if Secure Remote Access is installed. These scripts will prompt you for passwords.

  5. Follow these steps to upgrade Mobile Access support:
    1. Locate the Tools directory on the CD or Java Enterprise System web page.
    2. Copy the mobileaccess.zip file to a local hard drive.
    3. Unzip and untar the contents of the mobileaccess.zip file to a local directory.

      4. Note

      The GNU versions of the zip and tar commands (gunzip and gtar) should be used.

    4. Run the following command from the local directory:

      5. > ./setup

      Caution

      This step is required to upgrading Portal Server, regardless of whether Mobile Access support is actually used.

    To Upgrade the Gateway

Run the following command:

> patchadd 116738-19

Patch 116738-19 is intended for a Solaris SPARC system (refer to Portal Server 2004Q2 Patches for patch information for a Solaris x86 system).

Caution

The Gateway instance must be deleted and recreated after the upgrade.

    To Upgrade the Rewriter Proxy

Run the following command:

> patchadd 116742-19

Patch 116742-19 is intended for a Solaris SPARC system (refer to Portal Server 2004Q2 Patches for patch information for a Solaris x86 system).

Caution

The Rewriter Proxy instance must be deleted and recreated after the upgrade.

    To Upgrade the Netlet Proxy

Run the following command:

> patchadd 116740-19

Patch 116740-19 is intended for a Solaris SPARC system (refer to Portal Server 2004Q2 Patches for patch information for a Solaris x86 system).

Caution

The Netlet Proxy instance must be deleted and recreated after the upgrade.

    To Upgrade the Localization

Run the following command:

> patchadd 117012-05

Patch 117012-05 is optional depending on localization settings for a Solaris SPARC system (refer to Portal Server 2004Q2 Patches for patch information for a Solaris x86 system).

Verifying the Upgrade

If you customized your Identity Server 6.1 installation used with your Sun One Portal Server 6.2 software, you must manually redo the customizations in your new Identity Server 2004Q2 installation used with your Portal Server 6 2004Q2 software.

Here are several ways to verify that the upgrade was successful:

Sun Cluster Upgrade Information

This section provides an upgrade overview of Sun Cluster 3.1 4/04 from the version that shipped with Java Enterprise System 2003Q4. This section contains:

Upgrade Requirements and Restrictions

Observe the following requirements and restrictions when you upgrade to Sun Cluster 3.1 4/04 software:

You must upgrade all software to a version that is supported by Sun Cluster 3.1 4/04 software. For example, if a data service is supported on Sun Cluster 3.0 software but is not supported on Sun Cluster 3.1 4/04 software, you must upgrade that data service to the version of that data service that is supported on Sun Cluster 3.1 4/04 software. If the related application of that data service is not supported on Sun Cluster 3.1 4/04 software, you must also upgrade that application to a supported release.

The scinstall upgrade utility only upgrades those data services that are provided with Sun Cluster 3.1 4/04 software. You must manually upgrade any custom or third-party data services.

Sun Cluster 3.1 4/04 software supports:

Sun Cluster 3.1 4/04 software does not support:

Choosing a Sun Cluster Upgrade Method

Choose one of the following methods to upgrade your cluster software.

Nonrolling Upgrade

In a nonrolling upgrade, you shut down the cluster before you upgrade the cluster nodes. You return the cluster to production after all nodes are fully upgraded. You must use the nonrolling-upgrade method if one or more of the following conditions apply:

Rolling Upgrade

In a rolling upgrade, you upgrade one node of the cluster at a time. The cluster remains in production with services running on the other nodes. You can use the rolling-upgrade method only if all of the following conditions apply:

If your cluster configuration meets the requirements to perform a rolling upgrade, you can still choose to perform a nonrolling upgrade instead.

For overview information about planning your Sun Cluster configuration, see Chapter 1, “Planning the Sun Cluster Configuration” of the Sun Cluster Software Installation Guide for Solaris OS at http://docs.sun.com/doc/817-4229.

Web Server Upgrade Information

This section contains procedures for upgrading to Web Server SP2 from the previous Java Enterprise System 2003Q4 version. It contains the following topics:

For further Web Server information, refer to the following documentation:

    To Upgrade Web Server
  1. Login as superuser (root).
  2. Stop all running instances of Web Server and the Administration Server by entering:

    3. web_svr_base/https-instancename/stop
    web_svr_base/https-admserv/stop

    Default location for web_svr_base is /opt/SUNWwbsvr.

  3. Upgrade all shared components needed for the Java Enterprise System 2004Q2. (See Upgrading Shared Components.)
  4. Apply the following patches using patchadd(1M).

    5. Table 8-13  Web Server SP2 Patches

    Functional Area to Patch

    Patch ID Solaris Sparc

    Patch ID Solaris x86

    Web Server core (SUNWwbsvr)

    116648-05

    116649-05

    Web Server language packs

    117514-02

    117515-02

  5. Restart Web Server.
    To Remove Web Server Patches

If you decide to remove the Application Server patches, perform the following steps:

  1. Stop all running instances of the Web Server SP2.
  2. Become root:

    3. su root

    When prompted, type your root password.

  3. Remove the appropriate Web Server SP2 patches added in To Upgrade Web Server using patchrm(1M).
  4. Restart the Web Server SP2 instances.

Java Enterprise System 2004Q2 Compatibility Information

A new release of the Sun Java™ Enterprise System software strives for compatibility with the previous release. However, there are always some differences in the compatibility level of the two releases. This section discusses the issues that might impact your deployment when you upgrade from Java Enterprise System 2003Q4 to Java Enterprise System 2004Q2.

Note

This information does not address operating system or runtime compatibility. Although the Sun Solaris operating system provides a compatibility guarantee, other vendors might not guarantee the same compatibility level across different third party components, such as other J2EE runtimes that are supported by component products.

The compatibility issues addressed here concern only the Java Enterprise System and the interfaces that are exposed to customers.

This section addresses the following topics:

For information and instructions on upgrading, refer to the “Upgrading from Java Enterprise System 2003Q4” chapter in the Java Enterprise System Installation Guide (http://docs.sun.com/doc/817-5760).

For detailed platform and third party requirements, refer to the Java Enterprise System Release Notes (http://docs.sun.com/doc/817-5503) and the Java Enterprise System Installation Guide (http://docs.sun.com/doc/817-5760).

Data Preservation

Data is defined as the information you store in Java Enterprise System. For example, a user entry in Directory Server is regarded as data. Preservation is the act of retaining the stored data from one release to the next. In other words, the data will be the same after you upgrade as it was before you upgraded.

When you upgrade to Java Enterprise System 2004Q2, the data from Java Enterprise System 2003Q4 is preserved, with the following exceptions:

For instructions on upgrading component products and protecting your data, refer to the “Upgrading from Java Enterprise System 2003Q4” chapter in the Java Enterprise System Installation Guide (http://docs.sun.com/doc/817-5760).

Note

If you use the uninstaller, much configuration data is lost. For details, refer to Appendix G in the Java Enterprise System Installation Guide (http://docs.sun.com/doc/817-5760).

Configuration Preservation

Configuration is defined as the options and preferences that you have configured for Java Enterprise System and its component products. Configuration settings are typically stored in configuration files and are accessible from an Administration Console.

Note

If you use the uninstaller, much configuration data is lost. For details, refer to Appendix G in the Java Enterprise System Installation Guide (http://docs.sun.com/doc/817-5760).

When you upgrade to Java Enterprise System 2004Q2, the configuration from Java Enterprise System 2003Q4 is preserved, with the following exceptions:

API Compatibility

An Application Program Interface (API) is a publicly documented interface that developers use to extend functionality when building applications. In some situations, API changes are required so that the API will conform to publicly-available specifications and standards, or to correct API behavior.

Note

Rebuilding applications after a new release has been implemented is good practice.

Applications that have relied on component product APIs from the Java Enterprise System 2003Q4 release will run unchanged and without recompilation with Java Enterprise System 2004Q2 component product APIs, with the following exceptions:

Protocol Compatibility

Java Enterprise System components frequently make use of functional protocols. For example, Messaging Serverr supports the IMAP protocol which is widely used for communications with email clients.

When you upgrade to Java Enterprise System 2004Q2, the Java Enterprise System 2003Q4 protocols are maintained, with the following exceptions:

Command-Line Interfaces

Publicly documented command-line interfaces are frequently used for administrative purposes from a shell or prompt.

When you upgrade to Java Enterprise System 2004Q2, the command-line interfaces from Java Enterprise System 2003Q4 are preserved, with the following exceptions:

Log File Compatibility

Component products use log files to report various situations, such as status or errors. Log file compatibility refers to the data structures, messages and locations that are provided from one release to the next.

When you upgrade to Java Enterprise System 2004Q2, the log files from Java Enterprise System 2003Q4 are preserved, with the following exceptions:

Architectural Considerations

Some types of architectural changes might require you to consider restructuring your deployment.

When you upgrade to Java Enterprise System 2004Q2, the following architectural changes to release 2003Q4 might impact your deployment:

Deprecated and End-of-Feature Items

Deprecating or ending a feature refers to the process whereby an existing feature is removed from a product. To give you time to make adjustments for the change, the following events occur:

Features Removed in This Release

The following previously deprecated or end-of-feature items have been removed in this release:

Previously Deprecated or Ended Features

The following previously deprecated or end-of-feature items are scheduled for removal in a future release:

Refer to the release notes for the various component products for additional information.

New Deprecation Announcements

The following features will be removed in the first release of calendar year 2006:

Performance

Java Enterprise System strives to perform at or above the same level as the previous release. Under load, this release performs above or within approximately 95% of the previous release. We test extensively across many different scenarios at both the Java Enterprise System level and individual component level. However, your precise deployment and the applications that you have built to work with Java Enterprise System might have different results.



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.