Previous Contents Index Next |
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
> - Upgrading Shared Components
> - Administration Server Upgrade Information
> - Application Server Upgrade Information
> - Calendar Server Upgrade Information
> - Directory Server Upgrade Information
> - Directory Proxy Server Upgrade Information
> - Identity Server Upgrade Information
> - Instant Messaging Upgrade Information
> - Message Queue Upgrade Information
> - Messaging Server Upgrade Information
> - Mobile Access Upgrade Information
> - Portal Server Upgrade Information
> - Sun Cluster Upgrade Information
> - Web Server Upgrade Information

> ##

> Preparing for Upgrades

> In preparing to upgrade your servers, note the following:

> - Prior to upgrading your product(s), read the Java Enterprise System 2004Q2 Release Notes at http://docs.sun.com/doc/817-5503 and the release notes for each product to be upgraded.
> - Find the patches you need at the SunSolve web site:

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

> - Backup all data prior to upgrading.
> - Do not run Java Enterprise System 2004Q2 and any pre-Java Enterprise System 2004Q2 component products on the same system.
> - All components installed in a single system, must be upgraded to the same Java Enterprise System 2004Q2 level.
> - Upgrade shared components before the other Java Enterprise System component products (see Upgrading Shared Components).
> - To see a listing of Java Enterprise System 2003Q4 component products and their revisions see Component Products.
> - Apply the latest Solaris patch clusters appropriate to your system (see Applying Patch Clusters). In particular, apply the Solaris 8 recommended patch cluster and the J2SE Solaris 8 recommended patch cluster.
> - If you have a Sun Cluster installation you may need to apply: Sun Cluster 3.1 patch info doc for Solaris 8 users or Sun Cluster 3.1 Patch Info Doc for Solaris 9 users.

> ### 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
> - Upgrading J2SE Packages
> - Patch Contents

> ### 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:

> - Java Enterprise System Required component patch Solaris 8/9 SPARC
> - Java Enterprise System Required component patch Solaris 8 SPARC
> - Java Enterprise System Required component patch Solaris 9 SPARC
> - Java Enterprise System Required component patch Solaris 9 x86

> 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:

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

> 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
> - To Obtain J2SE 1.4.2
> - To Determine Where to Install the J2SE Packages
> - To Install the J2SE Packages
> - To Set the J2SE Symbolic Link
> - To Upgrade Supplemental Files

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

> 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 To Determine Where to Install the J2SE Packages To Install the J2SE Packages. To Set the J2SE Symbolic Link

> ##### To Obtain J2SE 1.4.2

> 1. To obtain J2SE 1.4.2 either obtain the packages from either of the following sources:
> - Java Enterprise System 2004Q2 Distribution:

> JavaEnterpriseSystem_base/Solaris_arch/Product/shared_components/
> Packages/

> - Sun java.sun.com:

> http://java.sun.com/j2se/1.4.2/download.html

> ##### 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:

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

> 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:

> pkgrm SUNWj3dmo SUNWj3man SUNWj3dev SUNWj3rt

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

> 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

> 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:

> # 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:

> 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:

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

> 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:

> 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
> - To Remove Administration Server Patches
> - To Troubleshoot Administration Server

> Note | If Administration Server belongs to a group of products sharing the same Administration Server, you must patch these products at the same time. If multiple Administration Servers share a single configuration directory server all instances of Administration Server must be patched at the same time. Upgrading Administration Server by applying patches only works for Administration Server installed on a Solaris system with SUNW as* packages. Patching upgrades the SSL certificate database. If you subsequently decide to back out the patches and you have changed the content of the certificate database, you must manually replay the changes after backing out the patches. Administration 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 Administration Server, reinstall the server certificate, and then enable SSL mode. Rolling upgrade for Sun Cluster data services is not supported.

> ##### To Apply Administration Server Patches

> 1. Obtain the patches for your platform and installed server component products.

> Required patches for SPARC� platforms include:

> - Sun Java Enterprise System 2004Q2 Recommended Patch Cluster for the Solaris™ operating system; (see Upgrading Shared Components)
> - Administration Server (see Administration Server Upgrade Information)
> - Calendar Server (see Calendar Server Upgrade Information)
> - Directory Proxy Server (see Directory Proxy Server Upgrade Information)
> - Directory Server (see Directory Server Upgrade Information)
> - Messaging Server (see Messaging Server Upgrade Information)

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

> 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

> 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)

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

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

> # /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.

> # /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

> 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

> - 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 (mpsadmserver sync-cds).
> - If backing out the patches did not work, typically this is because you did not synchronize settings for the upgraded Administration Server with the configuration directory server before you tried to back out patches. Try the entire process again, starting from To Apply Administration Server Patches.

> ##

> Application Server Upgrade Information

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

> - To Upgrade Supplemental Files
> - To Apply Application Server Patches
> - To Remove Application Server Patches

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

> http://docs.sun.com/coll/s1_asseu3_en

> 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:

> 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):

> 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:

> /asadmin stop-appserv/

> 2. Become root:

> 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:

> 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
> - To Upgrade Cluster Deployments
> - To Upgrade the User Management Utility
> - To Remove Calendar Server Patches

> ##### To Upgrade Non-Cluster Deployments

> 1. Log in as or become superuser (root).
> 2. Stop the Calendar Server:

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

> 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:
> - Shared components - NSPR, NSS, SASL, ICU, LDAPCSDK (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)
> - Communications Services User Management Utility (this is upgraded with Upgrading Shared Components and configured in To Upgrade the User Management Utility)
> - Messaging Server (see Messaging Server Upgrade Information)

> Note | All components installed in a single machine, must be upgraded to the same Java Enterprise System 2004Q2 level.

> 5. Apply the following Calendar Server patches using patchadd(1M).

> 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:

> 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:

> cal_svr_base/cal/sbin/stop-cal

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

> # 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:

> cal_svr_base/cal/sbin/stop-cal

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

> /var/opt/SUNWics5/csdb

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

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

> - Messaging Server (see Messaging Server Upgrade Information)
> - Communications Services User Management Utility (see To Remove the commadmin Patch)
> - Identity Server (see Identity Server Upgrade Information)
> - Directory Server (see Directory Server Upgrade Information)
> - Shared components - NSPR, NSS, SASL, ICU, LDAPCSDK (see Upgrading Shared Components)

> Make sure that all the products are running at Java Enterprise System 2003Q4 levels.

> 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:

> cd /var/opt/SUNWics5/csdb

> 2. Remove the database temporary files:

> rm __db.*

> 3. Remove the database log files:

> 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
> - To Correct the Schema
> - To Upgrade Cluster Configurations
> - To Remove Directory Server Patches
> - To Troubleshoot Directory Server
> - Upgrading From HAStorage to HAStoragePlus

> Notes | Directory Server belongs to a group of products sharing the same Administration Server. You must patch these products at the same time. Upgrading Directory Server by applying patches only works for Directory Server installed on a Solaris system with SUNWds* packages. During the patch upgrade process, some but not all instance-specific scripts under ServerRoot/slapd-serverID/ are backed up under ServerRoot/slapd-serverID/upgrade/bak_patch2/, and then regenerated to reflect changes made during the upgrade. If patches are backed out, the backed up scripts are restored. Patching upgrades the SSL certificate database. If you subsequently decide to back out the patches and you have changed the content of the certificate database, you must manually reapply the changes after backing out the patches. Directory 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 Directory Server, reinstall the server certificate, and then enable SSL mode. Refer to the Sun Java System Directory Server 5 2004Q2 Administration Guide at http://docs.sun.com/doc/817-5221 for instructions. Rolling upgrade for Directory Server as a Sun Cluster data service is not supported.

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

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

> # /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:

> 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:

> /usr/sbin/directoryserver stop
> /usr/sbin/directoryserver stop-admin

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

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

> 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:

> 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:

> /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:

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

> # /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:

> # /usr/sbin/directoryserver -d 5.2

> ##### To Troubleshoot Directory Server

> - If after applying the patches and setting the directoryserver(1M) command to apply to 5.2 by default (directoryserver -d 5.2), 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 (directoryserver sync-cds).
> - If backing out the patches did not work, typically this is because you did not synchronize settings for the upgraded Directory Server with the configuration directory server before you tried to back out patches. Try the entire process again, starting from To Apply Directory Proxy Server Patches.

> ### 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:

> - Why Use HAStoragePlus
> - Performing the Upgrade

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

> - To Disable Dependencies on the HAStorage Resource
> - To Update the File System Configuration
> - To Prepare the HAStoragePlus Resource
> - To Enable Dependencies on the HAStoragePlus Resource

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

> # scswitch -F -g ds-resource-group

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

> # scswitch -n -j ds-res
> # scswitch -r -j ds-res

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

> # scswitch -n -j as-res
> # scswitch -r -j as-res

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

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

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

> # scswitch -e -j hasp-res

> ##### To Enable Dependencies on the HAStoragePlus Resource

> 1. Bring the Directory Server resource group on line.

> # scswitch -Z -g ds-resource-group

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

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

> # scswitch -e -j ds-res

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

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

> # 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
> - To Remove Directory Proxy Server Patches
> - To Troubleshoot Directory Proxy Server

> Notes | Directory Proxy Server belongs to a group of products sharing the same Administration Server. You must patch these products at the same time. Upgrading Directory Proxy Server by applying patches only works for Directory Proxy Server installed on a Solaris system with SUNWdps* packages. Patching upgrades the SSL certificate database. If you subsequently decide to back out the patches and you have changed the content of the certificate database, you must manually replay the changes after backing out the patches. Directory Proxy 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 Administration Server, reinstall the server certificate, and then enable SSL mode.

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

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

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

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

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

> Figure 8-1 Directory Proxy Server Console

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

> 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
> - Upgrading Web Container Software
> - Running the Pre-Upgrade Script
> - Installing Identity Server
> - Running the Post-Upgrade Script
> - Verifying the Upgrade
> - Upgrading Multiple Instances of Identity Server

> Note | Perform the steps in To Correct the Schema before proceeding with Identity Server upgrade.

> ### Backing up Web Container Customized Files

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

> - Customized console JSP pages
> - Customized authentication JSP pages
> - JAR files for authentication and customized modules

> 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:

> - Identity Server: Administration Information
> - Identity Server Worksheets

> ### 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:

> - For Web Server 6.1 SP 2 see Web Server Upgrade Information
> - For Application Server 7 Update 3, see Application Server Upgrade Information.

> 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:

> 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:

> 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:

> 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:

> - Backs up Identity Server 6.1 by running the am2bak script
> - Removes the Identity Server 6.1 packages (but not Directory Server or web container packages) and then updates the /var/sadm/install/productregistry file to reflect that the packages have been removed
> - Writes the Sun_Java_System_Identity_Server_upgrade_log.timestamp log file to the /var/sadm/install/logs directory

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

> - Directory Server
> - Web Container:
> - Web server
> - Application server
> - Identity Server

> ##### To Run the Pre-Upgrade Script

> 1. Log in as or become superuser (root).
> 2. Verify that Directory Server is running. For example:

> # 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:

> # 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:

> - Upgrades the Identity Server schema in the Directory Server to Identity Server 6 2004Q2
> - Writes the Sun_Java_System_Identity_Server_upgrade_dit_log.timestamp log file to the /var/sadm/install/logs directory

> 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:

> # 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:

> 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:

> 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:

> - Access the Identity Server 6 2004Q2 console using the following URL:

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

> When the Identity Server login page appears, log in as amadmin. Click the “Service Configuration” tab. If the new Identity Server 6 2004Q2 services such as “Discovery Service” and “Liberty and Personal Profile Service” are available, the upgrade of Identity Server on the specific web container should be successful.

> - Review the status of the upgrade by checking the following log files in the /var/sadm/install/logs directory:
> - Pre-upgrade script (pre61to62upgrade):

> Java_Shared_Component_Install.timestamp

> - Sun Java Enterprise System installer:

> Java_Enterprise_System_Shared_Component_Install.timestamp
> Java_Enterprise_System_install.A timestamp
> Java_Enterprise_System_install.B timestamp
> Java_Enterprise_System_Summary_Report_install.timestamp

> - Post-upgrade script (Upgrade61DitTo62):

> Sun_Java_System_Identity_Server_upgrade_dit_log.timestamp

> ### 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:

> # 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:

> # ./amserver start

> 4. Upgrade the Identity Server instance you started in Step 3. See:
> - To Run the Pre-Upgrade Script
> - Installing Identity Server
> - Running the Post-Upgrade Script

> During the upgrade of the first instance, the post-upgrade script (Upgrade61DitTo62) upgrades the Identity Server schema to Identity Server 6 2004Q2. During subsequent upgrades of other instances, however, the post-upgrade script detects that the Directory Server has already been upgraded and does not try to upgrade it again.

> 5. Restart the instance you just upgraded.

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

> 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:

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

> 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
> - To Remove Instant Messaging Patches

> ##### 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:

> inst_msg_base/sbin/imadmin stop

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

> 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):

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

> 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:

> 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
> - To Upgrade Message Queue on Solaris
> - To Check the Message Queue Installation

> ##### 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:

> 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:

> # 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
> - To Upgrade Non-Cluster Deployments
> - To Upgrade Cluster Deployments
> - To Upgrade the User Management Utility
> - To Use commadmin with Schema 2 Compatibility Mode
> - To Remove Messaging Server Patches
> - To Remove the commadmin Patch

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

> 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:

> msg_svr_base/sbin/patch-config

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

> 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:

> 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:

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

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

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

> Take the following steps:

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

> 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:

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

> 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:

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

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

> 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:

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

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

> 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:

> msg_svr_base/install/patch/patchnumber/save

> patchnumber is the Messaging Server core patch.

> 8. Run the imsimta cnbuild command, as follows:

> msg_svr_base/sbin/imsimta cnbuild

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

> 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
> - Migrating Customized Environments
> - To Upgrade Systems With Mobile Access 6.2
> - To Upgrade Systems Without Mobile Access 6.2
> - Differences Between Mobile Access 6.2 and Mobile Access for Java Enterprise System 2004Q2
> - Configuration Files
> - /etc/opt/SUNWma/config.properties
> - /etc/opt/SUNWps/MAConfig.properties
> - Portal Desktop Types
> - Client Data

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

> 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:

> > ./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:

> - ps.uaprof.http.headers
> - storeProfileInClient
> - fediConfigRoot
> - schemaFile
> - vocabularyDefinitions

> #### /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:

> - ps.jsp.doc.root
> - ma.dispatch.servlet.name
> - ma.dispatch.parm.name
> - ma.compressor.max.url
> - ma.dispatch.error.page
> - ma.compressor.enable

> #### 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
> - Backing up Web Container Customized Files
> - Upgrading the Sun Web Container Software
> - Upgrading Identity Server
> - Using Third-Party Web Containers
> - Upgrading Portal Server
> - Verifying the Upgrade

> ### 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:

> - Customized console JSP pages
> - Customized authentication JSP pages
> - JAR files for customized modules
> - Customized sample Portal Server

> 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:

> - /opt/SUNWps (assuming a default installation location)
> - /etc/opt/SUNWps
> - /var/opt/SUNWps

> ### 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:

> - For Web Server 6.1 SP2 see:

> http://docs.sun.com/coll/S1_websvr61sp2_en

> - For Application Server 7 Update 3, see:

> http://docs.sun.com/coll/s1_asseu3_en

> 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:

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

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

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

> 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
> - To Upgrade the Gateway
> - To Upgrade the Rewriter Proxy
> - To Upgrade the Netlet Proxy
> - To Upgrade the Localization

> ##### To Upgrade Portal Server

> 1. Log in as root.

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

> 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:

> > ./unconfigureMA62

> 3. Run the following commands to install the patches:

> > 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):

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

> 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:

> > ./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:

> - Access the Identity Server 2004Q2 console using the following URL:

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

> When the Identity Server login page appears, log in as amadmin. Click the Service Configuration tab. If the new Portal Server 6 2004Q2 services such as Remote Portlets (WSRP) are available, the upgrade of Portal Server on the specific web container should be successful.

> - Review the status of the upgrade by checking the following log files in the /var/sadm/install/logs directory:
> - M Sun Java Enterprise System installer:

> Java_Shared_Component_Install.timestamp
> Java_Enterprise_System_install.Atimestamp
> Java_Enterprise_System_install.Btimestamp
> Java_Enterprise_System_Summary_Report_install.timestamp

> ##

> 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
> - Choosing a Sun Cluster Upgrade Method

> Note | For complete upgrade instructions, see the Chapter 5 “Upgrading Sun Cluster Software,” of the Sun Cluster Software Installation Guide for Solaris OS at http://docs.sun.com/doc/817-4229.

> ### Upgrade Requirements and Restrictions

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

> - The cluster must run on or be upgraded to at least Solaris 8 2/02 software, including the most current required patches.
> - The cluster hardware must be a supported configuration for 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:

> - Only nonrolling upgrade from Solaris 8 software to Solaris 9 software.
> - Direct upgrade only from Sun Cluster 3.x software.

> Sun Cluster 3.1 4/04 software does not support:

> - Any downgrade of Sun Cluster software.
> - Upgrade between architectures.
> - The Live Upgrade method to upgrade Solaris software in a Sun Cluster configuration.

> Note | Sun Cluster 3.1 4/04 does not require the installation of the shared component patch bundle described in Upgrading Shared Components.

> ### 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:

> - You are upgrading from Solaris 8 software to Solaris 9 software.
> - Any software products that you are upgrading, such as applications or databases, require that the same version of the software is running on all cluster nodes at the same time.
> - You are also upgrading VxVM.

> #### 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:

> - You are upgrading Solaris software only to a Solaris Update release, if at all.
> - For any applications or databases you must upgrade, the current version of the software can coexist in a running cluster with the upgrade version of that software.

> 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:

> - To Upgrade Web Server
> - To Remove Web Server Patches

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

> http://docs.sun.com/coll/S1_websvr61sp2_en

> ##### To Upgrade Web Server

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

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

> 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:

> 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:

> - Data Preservation
> - Configuration Preservation
> - API Compatibility
> - Protocol Compatibility
> - Command-Line Interfaces
> - Log File Compatibility
> - Architectural Considerations
> - Deprecated and End-of-Feature Items
> - Performance

> 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:

> - Calendar Server and Messaging Server. The schema has been changed to take advantage of Identity Server. If you are planning to migrate from LDAP Schema 1 to LDAP Schema 2 (for example, to implement the new Communications Express interface), any custom provisioning tools you are using will be affected. For information, refer to the Sun Java System Communications Express Schema Migration Guide (http://docs.sun.com/doc/817-5701).
> - Directory Server. The schema has been updated to incorporate minor changes. These changes are automatically upgraded.
> - Identity Server. The schema has been changed for the following: the Policy Service PluginConfig data has been changed to incorporate the new policy plugins, AuthenticatedUsers, WebServiceClients and LEAuthLevelCondition. In addition, the data of new services and attributes are also added.
> - Portal Server. Desktop sample JavaServer Pages (JSP) files have been updated. Users should not edit these JSP files. However, if the JSP files have been edited, the changes will need to be incorporate into any updated JSP files. User-modified files are saved in the patch backout database, or in the global backup that users are requested to make before upgrading Portal Server.

> 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:

> - Directory Server and Directory Proxy Server. Minor changes are taken into account by auto upgrade of the server's configuration during installation.
> - Identity Server. Configuration is not preserved. The AMConfig.properties file is replaced by a new version of this file. If you want to incorporate configuration changes from the old file, it is saved in the backup directory as AMConfig.properties.bak
> - Messaging Server. There are some highly recommended configuration changes which are highlighted during the upgrade process.

> ### 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:

> - Message Queue. Existing Java Enterprise System 3.0 clients (applications or components that directly instantiate administered objects) are compatible with Java Enterprise System 2004Q2. However, if they are to use the new administered object attributes, these clients will need to be rewritten.

> Note | Re-compiling Java Enterprise System 3.0.x clients with Java Enterprise System 2004Q2 will show which Java Enterprise System 3.0.x attributes have been renamed in Java Enterprise System 2004Q2. The old names will still work.

> For information on administered object attributes, see Chapter 4 and Appendix A of the Sun Java System Message Queue Java Client Developer’s Guide (http://docs.sun.com/doc/817-6026).

> ### 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:

> None identified.

> ### 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:

> - Identity Server. The amserver-create command is no longer available to create multiple Identity Server instances. You must use the underlying web container functionality to create multiple instances. For more information, refer to the Sun Java System Identity Server Administration Guide (http://docs.sun.com/doc/817-5709)
> - Message Queue. Scripts that start Java clients and which set administered object attribute values using command-line options are compatible with Java Enterprise System 2004Q2. However, if they are to use the new administered object attributes, they will need to be rewritten.

> For information on administered object attributes, see Chapter 4 and Appendix A of the Sun Java System Message Queue Java Client Developer’s Guide (http://docs.sun.com/doc/817-6026).

> - Portal Server and Portal Server Secure Remote Access. The only situation that applies is when an existing co-located Portal Server-Identity Server deployment is reinstalled with Portal Server and Identity Server no longer co-located on the same machine. In this case, a few additional arguments are required by the deploy and multi-instance command-line interfaces. If these arguments are not supplied, the command-line interfaces will interactively prompt for them.

> For more information, refer to the Sun Java System Portal Server Administration Guide (http://docs.sun.com/doc/817-5324).

> ### 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:

> None identified.

> ### 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:

> - Identity Server and Portal Server. In the 2004Q2 release, Portal Server and Identity Server can be installed on different machines.
> - For Application Server and Web Server—If you install Portal Server and Identity Server on different machines, the Identity Server SDK needs to be installed on the same machine that Portal Server is installed on.
> - For IBM WebSphere or BEA WebLogic—Portal Server and Identity Server must be installed on different machines.

> ### 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:

> - First, you are notified that functionality will be removed, including when it will be removed, and what replacement technology might be available.
> - At the expiration of that time, or at the next subsequent release, the functionality is removed and is no longer included in future releases.

> #### Features Removed in This Release

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

> - Identity Server. The amserver -create command is removed. Creating multiple Identity Server instances is now done using the underlying web container. For more information, refer to the Sun Java System Identity Server Administration Guide (http://docs.sun.com/doc/817-5709).

> #### Previously Deprecated or Ended Features

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

> - Message Queue. Message Queue client support for all releases of J2SE 1.3 will be dropped. J2SE 1.4 will continue to be supported. Sever broker properties have been deprecated. For details, refer to the Compatibility Issues section in the Sun Java System Message Queue Release Notes (http://docs.sun.com/doc/817-6022).
> - Messaging Server. For information on the deprecated features, refer to the Deprecated Features section in the Sun Java System Messaging Server Release Notes (http://docs.sun.com/doc/817-6363).

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

> #### New Deprecation Announcements

> - Application Server PE. Application Server PE will not be included in future versions of Java Enterprise System. Equivalent functionality is available with Application Server SE.
> - Message Queue. Message Queue client support for all releases of J2SE 1.3 will be dropped. J2SE 1.4 will continue to be supported. Sever broker properties have been deprecated. For details, refer to the Compatibility Issues section in the Sun Java System Message Queue Release Notes (http://docs.sun.com/doc/817-6022).

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

> - Calendar Server and Messaging Server. Going forward, no new features will be added to the Messenger Express or Calendar Express. Replacement functionality is available in the new Communications Express.

> Refer to the Deprecated Features section in the Sun Java System Messaging Server Release Notes (http://docs.sun.com/doc/817-6363) for additional information.

> - Portal Server. The NetMail application is being deprecated in this release. Replacement email functionality is now provided by Communications Express.

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