Previous      Contents      Index      Next
Sun Java Enterprise System 2005Q4 Upgrade Guide

Chapter 15
Communications Express

This chapter describes how to upgrade Communications Express to Java ES 2005Q4 (Release 4): Sun Java System Communications Express 6.2 2005Q4. The chapter provides a general overview of upgrade issues and procedures for the different upgrade paths supported by Java ES Release 4. The chapter covers upgrades on both the Solaris and Linux operating systems:

Overview of Communications Express Upgrades
Upgrading Communications Express from Java ES Release 3
Upgrading Communications Express from Java ES Release 2

Note	File locations in this chapter are specified with respect to a directory path referred to as CommsExpress-base. At least part of this path might have been specified as an installation directory when Communications Express was initially installed. If not, the Java ES installer assigned a default value. The default value of CommsExpress-base depends on operating system platform: Solaris: /opt/SUNWuwc Linux: /opt/sun/uwc

---

Overview of Communications Express Upgrades

This section describes the following general aspects of Communications Express that impact upgrading to Java ES 2005Q4 (Release 4):

About Java ES Release 4 Communications Express
Communications Express Upgrade Roadmap
Communications Express Data
Compatibility Issues
Communications Express Dependencies

About Java ES Release 4 Communications Express

Java ES Release 4 Communications Express mostly represents bug fixes. There are a few new features with respect to Release 3: mail filter support, address book sharing, and proxy authentication.

Communications Express Upgrade Roadmap

Table 15-1 shows the supported Communications Express upgrade paths to Java ES Release 4. The table applies to both Solaris and Linux operating systems.

Table 15-1  Upgrade Paths to Java ES Release 4:
Sun Java System Communications Express 6.2 2005Q4 

Java ES Release	Communications Express Version	General Approach	Re-configuration Required
Release 3	Sun Java System Communications Express 6 2005Q1	Direct upgrade: Perform by applying patches and re-configuring Messaging Server component.	Configuration files
Release 2	Sun Java System Communications Express 6 2004Q2	Direct upgrade: Perform by applying patches and re-configuring Messaging Server component.	Configuration files
Release 1	None	No upgrade:
Pre-dates Java ES releases	None	No upgrade:

Communications Express Data

The following table shows the type of data that could be impacted by an upgrade of Communications Express software.

Table 15-2  Communications Express Data Usage

Type of Data	Location	Usage
Configuration data:	Local configuration directory var/CommsExpress-base/WEB-INF/config/uwcauth.properties var/CommsExpress-base/WEB-INF/config/uwcconfig.properties var/CommsExpress-base/WEB-INF/config/uwclogging.properties MessagingServer-base/config/msg.conf and other configuration files for configuring Messaging Server MEM (webmail)	Configuration of Communications Express, including Messaging Server MEM (webmail)
Web container configuration	Web Server: server.policy and server.xml files in WebServer-base/https-hostname/config Application Server (Java ES Release 3 and 4): server.policy and domain.xml files in AppServer8Config-base/domains/domainName/config Application Server (Java ES Release 2): server.policy and server.xml files in AppServer7Config-base/domains/domainName/config	Configuration of Communications Express web container instance.
Directory schema	Directory Server user/group directory	For user attributes needed to support end users

Compatibility Issues

Release 4 Communications Express does not introduce any interface changes and is backwardly compatible with earlier versions.

Communications Express Dependencies

Communications Express dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Communications Express software. Changes in Communications Express interfaces or functions, for example, could require upgraded version of components upon which Communications Express depends. The need to upgrade such components depends upon the specific upgrade path.

Communications Express has dependencies on the following Java ES components:

Shared components.   Communications Express has dependencies on specific Java ES shared components (see Table 1-6).
Web Container.   Communications Express depends upon web container services, which can be provided either by Java ES Web Server or Java ES Application Server.
Access Manager (or Access Manager SDK).    Communications Express depends upon Access Manager to provide authentication and authorization services for end users, including single sign-on. If Access Manager is run on a remote computer, then Access Manager SDK must be available locally.
Messaging Server.   Communications Express is used to provide web-based access to Messaging Server. In fact Communications Express directly employs the Messaging Server MEM component to access other Messaging Server back-end components, such as the Messaging Server Store and MTA components.
Calendar Server.   Communications Express is used to provide web-based access to Calendar Server.
Directory Server.   Communications Express stores configuration data and also accesses user data stored in Directory Server. As a result, Communications Express upgrades might require upgrades of Directory Server or extensions of directory schema.
Directory Preparation Tool.   Communications Express uses the Directory Preparation Tool to prepare Directory Server to support Communications Express functions. As a result, Communications Express upgrades might depend upon preparation of the directory to support new functions.

---

Upgrading Communications Express from Java ES Release 3

This section includes information about upgrading Communications Express from Java ES 2005Q1 (Release 3) to Java ES 2005Q4 (Release 4). The section covers the following topics:

Introduction
Release 3 Communications Express Upgrade
Multiple Instance Upgrades

Introduction

When upgrading Java ES Release 3 Communications Express to Release 4, consider the following aspects of the upgrade process:

General Upgrade Approach.   The upgrade is performed by applying patches to the Release 3 version. Re-configuration of the included Messaging Server MEM component is achieved using two configuration utilities and by importing configuration data into Directory Server.
Upgrade Dependencies.   While Calendar Server has dependencies on a number of Java ES shared components (see Table 1-6), Release 4 Calendar Server is compatible with the Release 3 versions of these components. Upgrade of these shared components is therefore optional with respect to upgrade of Calendar Server to Release 4.

In addition, Release 4 Communications Express is dependent upon a web container and on Access Manager, as described in Communications Express Dependencies. However, these are soft upgrade dependencies; upgrade of these components is optional with respect to upgrade of Communications Express to Release 4.

However, Communications Express has hard upgrade dependencies on both Calendar Server, for which it provides web-based access, and on Messaging Server for which it also provides web-based access using the Messaging Server MEM component. Both Calendar Server and Messaging Server must therefore be upgraded to Release 4 before Communications Express can be upgraded to Release 4.

In addition, Release 4 Communications Express has a hard upgrade dependency on Directory Preparation Tool; Release 4 Directory Preparation Tool is required to prepare Directory Server for Communications Express functions.

Backward Compatibility.   Release 4 Communications Express is backwardly compatible with the Release 3 version.
Upgrade Rollback.   Rollback of the Release 4 upgrade of Communications Express to Release 3 is achieved by first removing the changes made to Directory Server, removing changes to local configuration files, and removing the patches applied during the upgrade.
Platform Issues.   The general approach for upgrading Communications Express is the same on both Solaris and Linux operating systems, however the patching technologies are different. The upgrade process therefore includes platform-specific procedures.

Release 3 Communications Express Upgrade

This section describes how to perform an upgrade of Communications Express from Java ES Release 3 to Java ES Release 4 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:

Pre-Upgrade Tasks
Upgrading Release 3 Communications Express (Solaris)
Upgrading Release 3 Communications Express (Linux)
Verifying the Upgrade
Post-Upgrade Tasks
Rolling Back the Upgrade (Solaris)

Pre-Upgrade Tasks

Before you upgrade Communications Express you should perform the tasks described below.

Verify Current Version Information

You can verify the current version of Communications Express by accessing the Communications Express login page, which shows the current version number.

http://hostName:port/uwc/auth

Table 15-3  Communications Express Version Verification Outputs

Java ES Release	Communications Express Version Number
Release 2	Sun Java System Communications Express 6 2004Q2
Release 3	Sun Java System Communications Express 6 2005Q1
Release 4	Sun Java System Communications Express 6 2005Q4

Upgrade Communications Express Dependencies

It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Java ES Release 4. However, Communications Express has hard upgrade dependencies only on Messaging Server, Calendar Server, and Directory Preparation Tool. Upgrading of other Java ES Release 3 components upon which Communications Express depends is therefore optional.

However, if you choose to upgrade all Communications Express dependencies, they should be upgraded in the following order, all before you upgrade Communications Express. You can skip any that might already have been upgraded.

Shared Components.  Instructions for upgrading Java ES shared components to Release 4 are provided in Chapter 2, "Upgrading Java ES Shared Components".
Directory Server.  Instructions for upgrading Directory Server to Release 4 are provided in Chapter 4, "Directory Server and Administration Server".
Web Container Software.  Instructions for upgrading Web Server or Application Server are provided in Chapter 6, "Web Server" and Chapter 9, "Application Server", respectively.
Access Manager (Access Manager SDK).  Instructions for upgrading Access Manager to Release 4 are provided in Chapter 11, "Access Manager".
Directory Preparation Tool.   Release 4 Directory Preparation Tool needs to have been run against Directory Server before configuring Release 4 Communications Express. If Release 4 Directory Preparation Tool has not already been run against Directory Server, upgrade Directory Preparation Tool to Release 4 and use it to modify and extend the schema of Directory Server (see Chapter 12, "Directory Preparation Tool" for procedures).
Messaging Server.    Messaging Server components need to be upgraded to Release 4 to support Release 4 Communications Express. Instructions for upgrading Messaging Server to Release 4 are provided in Chapter 13, "Messaging Server".
Calendar Server.    Calendar Server components need to be upgraded to Release 4 to support Release 4 Communications Express. Instructions for upgrading Calendar Server to Release 4 are provided in Chapter 14, "Calendar Server".

Back Up Communications Express Data

The Communications Express upgrade from Release 3 to Release 4 requires re-configuration of Messaging Server MEM. The local changes can be rolled back, so there is no need to back up any data.

Obtain Required Configuration Information and Passwords

You have to log in as superuser to perform the upgrade. If you are using Web Server as a web container, no configuration information is needed. However if you are using Application Server as a web container, you will need the Application Server administrator user ID and password.

Upgrading Release 3 Communications Express (Solaris)

This section discusses considerations that impact the upgrade procedure for Communications Express followed by a description of the procedure itself.

Upgrade Considerations (Solaris)

The upgrade of Communications Express software to Java ES Release 4 takes into account the following considerations:

Communications Express includes components used to provide web-based access to Calendar Server and a Messaging Server MEM component used to provide web-based access to Messaging Server back-end components. The upgrade patches encompass all these components.
All Communications Express components should be deployed to the same web container. The web container should be shut down before patches are applied to the installed image.
The Release 4 Communications Express upgrade patches for Solaris OS are shown in the following table:

Table 15-4  Patches1 to Upgrade Communications Express on Solaris 

Description	SPARC Solaris 8, 9, & 10	X86 Solaris 9 & 10
Communications Express core	118540-21	118541-21
Communications Express localization	118042-16	118042-16

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

Upgrade Procedure (Solaris)

The procedure documented below applies to all Communications Express components on the computer being updated.

Obtain the required patches, based on Table 15-4.

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

Log in as root or become superuser.

su -

Stop Communications Express by stopping its web container.

Web Server:
WebServer-base/https-instanceName/stop

Application Server:
AppServer8-base/bin/asadmin stop-domain domainName

If you have not already done so, upgrade any shared components you wish to upgrade to Release 4.

See Upgrade Communications Express Dependencies.

Apply the appropriate Communications Express patches in Table 15-4.

patchadd patch_ID

Confirm that the patch upgrade was successful:

showrev -p | grep uwc

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

Migrate configuration data from existing configuration files to Release 4 candidate configuration files.

cd CommsExpress-base/sbin
./patch-config CommsExpress-base/install/patch/patch_ID

This command prompts you for the current configuration directory and then backs up the existing configuration files. Then it merges configuration parameter values in these files with Release 4 template configuration files to create new Release 4 candidate configuration files. You should check these new files for possible conflicts, as described in the Special Installation Instructions section of the patch readme file.

Install the Release 4 candidate configuration files, making them the active configuration.

./install-newconfig CommsExpress-base/install/patch/patch_ID

This command installs the new Release 4 configuration files in their correct Release 4 locations.

Remove the JSP class cache for Communications Express that is maintained by the web container.

For the procedure, see the documentation for your web container (Web Server or Application Server).

Restart Communications Express by restarting its web container.

Web Server:
WebServer-base/https-instanceName/start

Application Server:
AppServer8-base/bin/asadmin start-domain domainName
     --user admin_ID --password password

Upgrading Release 3 Communications Express (Linux)

This section discusses considerations that impact the upgrade procedure for Communications Express followed by a description of the procedure itself.

Upgrade Considerations (Linux)

The upgrade of Communications Express software to Java ES Release 4 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that the Linux Release 4 upgrade patches differ from the Solaris patches.

The Release 4 Communications Express upgrade patches for Linux OS are shown in the following table:

Table 15-5  Patches1 to Upgrade Communications Express on Linux 

Description	Patch ID and RPM names
Communications Express core	118542-21 sun-uwc-6.1-7.21.i386.rpm
Communications Express localization	118044-14 sun-uwc-l10n-Locale-6.1-11.9.i386.rpm

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

Upgrade Procedure (Linux)

The procedure documented below applies to all Communications Express components on the computer being updated.

Caution	An upgrade from Java ES Release 3 to Java ES Release 4 on Linux cannot be rolled back.

Obtain the required patches using the patch numbers and RPM names from Table 15-5. Use this information to obtain the version numbers for the RPM.

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

Log in as root or become superuser.

su -

Stop Communications Express by stopping its web container.

Web Server:
WebServer-base/https-instanceName/stop

Application Server:
AppServer8-base/bin/asadmin stop-domain domainName

If you have not already done so, upgrade any shared components you wish to upgrade to Release 4.

See Upgrade Communications Express Dependencies.

Apply the RPMs for Communications Express in Table 15-5.

For example:

rpm -Fvh sun-uwc-6.1-7.21.i386.rpm

Confirm that the patch upgrade was successful:

rpm -qa | grep uwc

The output should return the version of RPM in Step 5.

Migrate configuration data from existing configuration files to Release 4 candidate configuration files.

cd CommsExpress-base/sbin
./patch-config CommsExpress-base/install/patch/patch_ID

This command prompts you for the current configuration directory and then backs up the existing configuration files. Then it merges configuration parameter values in these files with Release 4 template configuration files to create new Release 4 candidate configuration files. You should check these new files for possible conflicts, as described in the Special Installation Instructions section of the patch readme file.

Install the Release 4 candidate configuration files, making them the active configuration.

./install-newconfig CommsExpress-base/install/patch/patch_ID

This command installs the new Release 4 configuration files in their correct Release 4 locations.

Remove the JSP class cache for Communications Express that is maintained by the web container.

For the procedure, see the documentation for your web container (Web Server or Application Server).

Restart Communications Express by restarting its web container.

Web Server:
WebServer-base/https-instanceName/start

Application Server:
AppServer8-base/bin/asadmin start-domain domainName
     --user admin_ID --password password

Verifying the Upgrade

You can verify the current version of Communications Express by accessing the Communications Express login page, which shows the current version number.

http://hostName:port/uwc/auth

Once logged in, check the upgraded user interface for the new mail tab and old email and calendar events (if you are using those channels).

Also, you can check the log files for the various steps in the upgrade procedure:

CommsExpress-base/install/patch/118540-21.
CommsExpress-base/patch-config_20050729164754.log
CommsExpress-base/install-newconfig_20050729164838.log

Post-Upgrade Tasks

There are no post-upgrade tasks beyond the steps described in Upgrade Procedure (Solaris) and Upgrade Procedure (Linux).

Rolling Back the Upgrade (Solaris)

This section describes considerations that impact the upgrade rollback procedure for Communications Express followed by the procedure itself.

Rollback Considerations (Solaris)

The procedure for rolling back the upgrade to Release 4 of Communications Express is pretty much the reverse of the procedure for upgrading to Release 4. The re-configurations are rolled back and the patches are removed.

Rollback Procedure (Solaris)

Log in as root or become superuser.

su -

Stop Communications Express by stopping its web container.

Web Server:
WebServer-base/https-instanceName/stop

Application Server:
AppServer8-base/bin/asadmin stop-domain domainName

Roll back the changes made to the Directory Server configuration directory being used by Communications Express.
Roll back the re-configuration performed in Step 8.

cd CommsExpress-base/sbin
./uninstall-newconfig CommsExpress-base/install/patch/patch_ID

Remove the patches in Table 15-4.

patchrm patch_ID

Restart Communications Express by restarting its web container.

Web Server:
WebServer-base/https-instanceName/start

Application Server:
AppServer8-base/bin/asadmin start-domain domainName
     --user admin_ID --password password

Multiple Instance Upgrades

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

In the case of load-balanced instances of Communications Express, you can perform a rolling upgrade in which you upgrade the Communications Express instances sequentially without interrupting service. You upgrade each instance of Communications Express while the others remain running. You perform the upgrade of each instance as described in Release 3 Communications Express Upgrade.

---

Upgrading Communications Express from Java ES Release 2

The procedure for upgrading Java ES 2004Q2 (Release 2) Communications Express to Release 4 is the same as that for upgrading Release 3 Communications Express to Release 4, with a couple of exceptions, noted below.

Note	This section applies to the case in which Communications Express is deployed in a Release 2 Web Server web container, but does not apply to the case in which Communications Express is deployed in a Release 2 Application Server web container. The latter case is not currently supported.

Upgrade Communications Express Dependencies

The pre-upgrade tasks for upgrading Java ES Release 2 Communications Express to Release 4 are similar to those for upgrading Release 3 Communications Express to Release 4, with the exception that the upgrade of Communications Express dependencies should include the upgrading to Release 4 of all shared components (see Table 1-6) and all locally-resident product components upon which Communications Express depends.

When upgrading Communications Express dependencies, they should be upgraded in the following order, all before you upgrade Communications Express. You can skip any that might already have been upgraded.

Shared Components.  Instructions for upgrading Java ES shared components to Release 4 are provided in Chapter 2, "Upgrading Java ES Shared Components".
Directory Server.  Directory Server rarely resides on the same computer as Communications Express, however, instructions for upgrading Directory Server to Release 4 are provided in Upgrading Directory Server and Administration Server from Java ES Release 2.
Web Container Software.  Instructions for upgrading Web Server or Application Server are provided in Upgrading Web Server from Java ES Release 2 and Upgrading Application Server from Java ES Release 2, respectively.
Access Manager (Access Manager SDK).  Instructions for upgrading Access Manager to Release 4 are provided in Upgrading Access Manager from Java ES Release 2.
Directory Preparation Tool.  Directory Preparation Tool rarely resides on the same computer as Communications Express, however, instructions for upgrading Directory Preparation Tool and running it against Directory Server are provided in Upgrading Directory Preparation Tool from Java ES Release 2.
Messaging Server.   Messaging Server MTA needs to be upgraded to Release 4 to support Release 4 Communications Express. Instructions for upgrading Messaging Server to Release 4 are provided in Upgrading Messaging Server from Java ES Release 2
Calendar Server.   Calendar Server rarely resides on the same computer as Communications Express, however, instructions for upgrading Calendar Server to Release 4 are provided in Upgrading Calendar Server from Java ES Release 2

Release 2 Communications Express Upgrade

The procedure for upgrading Communications Express from Release 2 to Release 4 depends on the web container in which you are deploying Communications Express software.

Upgrading Release 2 Communications Express: Web Server Web Container

To upgrade Release 2 Communications Express to Release 4, when deploying into a Web Server web container that has been upgraded to Release 4, follow the instructions in Upgrading Release 3 Communications Express (Solaris) or Upgrading Release 3 Communications Express (Linux), except substitute Release 2 wherever Release 3 is referenced.

Upgrading Release 2 Communications Express: Application Server Web Container

The upgrade of Release 2 Communications Express to Release 4, when deploying into an Application Server web container that has been upgraded to Release 4, is not currently supported.

Previous      Contents      Index      Next

---

Part No: 819-2331-13.   Copyright 2006 Sun Microsystems, Inc. All rights reserved.