Sun Java Communications Suite 6 Upgrade Guide

This document describes the best practices for upgrading earlier versions of Communications Suite products to version 6. In this guide we use the terms products, product components, and shared components. Products are things like the Messaging Server, Calendar Server, Delegated Administrator and Instant Messaging Server. Product components are functional parts of the products. For example, for Messaging Server there are message stores, relays, messaging multiplexors. Calendar Servers has front-end and back-end servers. Shared resources are software that are not part of the Communications Suite or other support products, but are required for Communications Suite products to operate. Examples include NFS, SASL, Java.

Communications Suite 6 consists of a number of individual products, product components and shared resources, and there is no single system utility that upgrades all Communications Suite components at once. Upgrading a Communications Suite deployment consists of a upgrading component-by-component and computer-by-computer, using the component-specific upgrade procedures described in this document. Some of these procedures are as simple as adding upgrade patches to the existing software. Other procedures require considerably more planning, preparation and complexity. Proper upgrading starts with knowing what products you want to upgrade and the order in which to upgrade them.

Define Your Target Deployment

A successful upgrade depends on knowing where you are (your current deployment) and where you are going (your target deployment). By defining your target deployment, you will know what products and components you need to upgrade and which ones can remain as is.

These are the three most common Communications Suite upgrade scenarios:

1. Upgrade for a Product Feature. There is a specific feature you want from a specific product and you are only interested in upgrading the products/components necessary to support that feature.
   
   In this scenario, you simply upgrade the desired product. See the upgrade section below describing the product you wish to upgrade.
   
   
2. Upgrade to use Sun Convergence. You only want to upgrade the products and components necessary to use Sun Convergence.
   
   The minimum product versions that can still run Convergence are listed in Product Version Compatibility Requirements for Convergence 1.0.
   
   
3. You want to upgrade everything to latest release.
   
   You upgrade each product individually, host-by-host. See Requirements for Communications Suite 6

Once you have chosen the scenario that best fits your situation, you will know what products you will need to upgrade.

Determine the Sequence of Product Upgrades

The order in which the Communications Suite product and versions are upgraded may be critical. Use the following guidelines to determine the upgrade sequence for Communications Suite products:

• If you are upgrading Communications Express from a version earlier than 6.3, then you must upgrade to Messaging Server 6.3 or later first.

• For upgrading a pre-6.3 Messaging Server you must upgrade the messages store components to 6.3 or later before upgrading the webmail server (previously called MEM) to 6.3 or later.

The rest of this guide describes how to upgrade each of the Communications Suite products.

Upgrading Messaging Server

See Messaging Server 7.0 Upgrade

Upgrading Messaging Server in an HA (High Availability) Environment

See Upgrading to Messaging Server 7.0 in an HA Environment

Upgrading Calendar Server in the Solaris OS

See Calendar Server 6.3 Upgrade

Upgrading the Calendar Server in an HA (High Availability) Environment

See Upgrading Calendar Server 6.3 in an HA Environment

Upgrading Instant Messaging Server

See Instant Messaging 7.3 Upgrade

Upgrading the Instant Messaging Server in an HA (High Availability) Environment

See Upgrading to Instant Messaging 7.3 in an HA Environment

Installing Sun Convergence

Sun Convergence is a new product for Communications Suite 6, so there are not upgrade procedures.
See the Communications Suite 6 Installation Scenario - Convergence installation instructions.

Upgrading Delegated Administrator

See Delegated Administrator Upgrade.

Upgrading comm_dssetup.pl

It is important to run the latest version of comm_dssetup.pl to prepare the schema, index, and data in your Directory Server to work with Messaging Server, Calendar Server, Instant Messaging, Delegated Admin or any products that depend on the Directory Server.

Run commpkg upgrade to upgrade comm_dssetup.pl and then run perl comm_dssetup.pl. For upgrade details see commpkg upgrade Usage

Upgrading Communications Express

See Communications Express 6.3 Upgrade.

Upgrading Sync

Using Sun Java System Communications Sync with Communications Suite 6 and Sun Convergence requires the following:

1. Sun Java System Communications Sync Version 3.1. Note that Sync 3.1 is the same as 3.0 with additional fixes.
2. Installation or upgrade to Communications Express 6.3. (See Communications Express 6.3 Upgrade or the Sun Java Communications Suite 6 Installation Guide.)

Upgrading Outlook Connector

See Connector for Microsoft Outlook 7.3 Upgrade Guide

Additional Communications Suite 6 Upgrade Information

Upgrading to Calendar Server 6.3 with Convergence

This section describes how to upgrade Calendar Server to use Sun Convergence. The version required is Calendar Server 6.3 with the latest patches installed. Upgrading consists of choosing an upgrade strategy, then upgrading each of the individual servers using that strategy. The procedure for upgrading individual servers depends on the version of Calendar Server you are currently running.

To upgrade the Calendar Server from Communications Suite Release 5 to Release 6, you use the commpkg upgrade command. Both versions are 6.3, but commpkg upgrade installs the required patches. To upgrade from 6.2, see To Upgrade From Calendar Server 6.2 . To upgrade from a version earlier then 6.2, refer to the Chapter 5, Upgrading Calendar Server of the Sun Java Communications Suite 5 Upgrade Guide to upgrade to 6.3, then return here for instructions on how to apply the appropriate patches.

This chapter consists of the following sections:

Calendar Server Upgrade Strategies

There are two possible Calendar Server upgrade strategies: the parallel system upgrade or the in-place upgrade.

In an in-place upgrade, the existing software is upgraded to the new version in the same location.

In a parallel system upgrade, the existing software remains operating while the new version is installed in another location. A parallel system upgrade is useful for deployments consisting of multiple servers in a distributed network. The servers interoperate by using adjacent builds (in adjacent directories) so that the network can be upgraded in phases.

Each strategy has its advantages and disadvantages:

• In a parallel system upgrade, users have access to the calendar (though, readonly) throughout the upgrade process. During an in-place upgrade, some downtime is incurred.

• A parallel system upgrade limits the impact on global and distributed services during the upgrades.

• In a parallel system upgrade, a smaller staff is required to administer the upgrades on many distributed machines. Conversely, this approach limits the extended downtime a small staff needs to upgrade many machines together.

• If the upgrade is not successful, parallel system upgrades offer an easier roll-back procedure. Parallel system upgrades reduce the risk of attempting to change all installations at once before being able to verify that the solution is workable. In-place upgrades have a more complex roll-back procedure.

• Parallel system upgrades require additional hardware. In-place upgrades do not require additional hardware.

Upgrade Strategy for Calendar Server Deployments Using the DWP Protocol For Calendar Server deployments that use the Database Wire Protocol (DWP) protocol, you are strongly urged to consider a parallel system upgrade. Here's why: DWP design constraints require all nodes in a distributed deployment to be upgraded at the same time. With its versionless state, the DWP protocol presumes (requires) the front-end and back-end servers to be the same build/version. For example, suppose an organization running Calendar Server with DWP has back-end servers in Europe, Asia, and the Americas and front-end servers in a multitude of countries. To perform an in-place upgrade, this deployment would need to shut down the entire Calendar Server network. A parallel system upgrade would enable the existing Calendar Servers to continue running while the network is upgraded in phases.

Parallel System Upgrade Procedures

In a parallel system upgrade, you do the following:

1. Create a separate new Calendar Server environment. Refer to the Sun Java Communications Suite 5 Deployment Planning Guide for details.
   
   
2. Set the existing Calendar server to a read-only mode and inform users that calendar entries cannot be created or modified until the migration is complete.
   
   Set caldb.berkeleydb.readonly to yes in ics.conf and restart the services.
   
   
3. Migrate the configuration and calendar data to the new environment. (See the version-specific section.)
   
   
4. Switch over to the new system and verify that everything works.
   
   End users, or any applications that depend on this server, will need to connect to this box instead of the old box.
   
   
5. Inform users that calendar entries can be created or modified and the migration is complete.
   
   
6. Shut down the legacy servers.
   
   
7. If the switchover does not work, switch back to the legacy servers.

In-place Upgrade Procedures

In an in-place upgrade, you do the following:

1. Back up your calendar database.
   
   See csbackup
   
   
2. Perform the upgrade procedures as described in the following sections.
   
   
3. Verify that the new system works.
   
   For example, check that users can log in and create events and to-do's.
   
   
4. If the new system does not work, remove the upgrade patches and then restore the data.
   
   Restore the database save in step 1. See csrestore
   

   Note You cannot remove the upgrade patches and restore the data in Linux by using an in-place upgrade.

   The rest of this section describes how to upgrade your individual Calendar Servers by using these two strategies.

Upgrading Individual Calendar Servers

Whether you are doing an in-place or parallel upgrade, the process for upgrading individual servers is the same. How those individual Servers are upgraded to use Sun Convergence depends on whether you are using the version 6.3 or an earlier version of Calendar Server. To upgrade from a version earlier then 6.2, refer to the Chapter 5, Upgrading Calendar Server of the Sun Java Communications Suite 5 Upgrade Guide to upgrade to 6.3, then return here for instructions on how to apply the appropriate patches. To upgrade from 6.3 or 6.2 you'll need to install the latest patches listed in Release Notes . Detailed instructions are provided in later sections.

The localization patches and packages are no longer required separately, as localization resources are bundled with core packages. Before applying this patch, remove the old l10n packages if installed. For example:

pkgrm -n SUNWics-l10n

or

pkgrm -n SUNWfrics SUNWdeics SUNWesics SUNWjaics SUNWkoics SUNWzhics SUNWtwics

for Linux:

rpm -e sun-calendar-core-l10n

or

rpm -e sun-calendar-core-fr
rpm -e sun-calendar-core-de
rpm -e sun-calendar-core-es
rpm -e sun-calendar-core-ja
rpm -e sun-calendar-core-ko
rpm -e sun-calendar-core-zh
rpm -e sun-calendar-core-zh_TW

Other Calendar Server Upgrade Notes:

• At some sites, Calendar Server 6.3 might not start after patching. If this problem occurs, follow the procedure described in the Known Issues section of Calendar Server 6.3 Release Notes .
• Calendar Server should be shut down when patches are being applied to the installed image.
• In architectures in which different Calendar Server subcomponents reside on different computers, for example, Calendar Server back-end store on one computer and Calendar Server front-end processes (such as cshttpd) on another, the upgrade must be performed on all such computers.
• The Calendar Server upgrade applies to multiple Calendar Server subcomponents on one computer using the same installed image.
• Data created in the Solaris x86 version of Calendar Server 6.3 patch 121658-19 or earlier is corrupted when you upgrade to patch 121658-20 or later. This issue occurs on Solaris x86 platforms only (CR 6642958). With patch 121658-20 and later, Calendar Server uses the new Berkeley Database library, which is incompatible with the database created by earlier versions. In order to use the database created by patch 121658-19 (or prior) with this patch, you must update the database. See Release Notes for details on how to update the database and further details.
• Calendar Server 6.3 requires the software dependencies listed in the Release Notes . For a list of all Communications Suite requirements, see the Requirements for Communications Suite 6.

If you want to upgrade Calendar Server 6.3 so that it can be used by Sun Convergence, you can simply run the commpkg upgrade command

To Upgrade From Calendar Server 6.3

Note that Communications Suite 5 and 6 both use Calendar Server 6.3, but Communications Suite 6 has the required patches that work with Sun Convergence.

1. Run commpkg upgrade command

To Upgrade From Calendar Server 6.2 on Solaris

To upgrade Calendar Server 6.2 to Convergence-enabled Calendar Server 6.3, use the following directions:

1. Obtain the required patch. See Release Notes .
   
   You can download patches to /tmp from: http://sunsolve.sun.com.
   
   
2. Log in to the machine where you are upgrading Calendar Server (as superuser or root).
   
   > su -
   
   
3. Stop Calendar Server if it is running.
   
   cal-svr-base/cal/sbin/stop-cal
   
   
4. If you have not already done so, upgrade shared components to Communications Suite 6.
   
   See Communications Suite Requirements.
   
   
5. Apply the Calendar Server core patch (see Release Notes ).
   
   patchadd <patch_ID>
   
   
6. Confirm that the patch upgrades were successful:
   
   showrev -p | grep ics
   
   The output should return the versions of patch IDs applied in Step 5.
   
   
7. Reconfigure Calendar Server.
   
   cd cal-svr-base/sbin
   ./csconfigurator.sh -noconsole -nodisplay -novalidate
   
   The -noconsole -nodisplay -novalidate arguments pick up the existing Calendar Server 6.x configuration values and perform the necessary reconfiguration for the upgraded software.
   
   If the Calendar Server 6.x installation had been configured in nonhosted domain (legacy) mode, the configurator gives the choice either to stay in that mode or switch to hosted domain mode, the default for this version of Calendar Server. Switching to hosted domain mode is not reversible.
   
   The csconfigurator command is documented in the Calendar Server Administration Guide .
   
   
8. Move Calendar Server data files to a temporary location.
   
   mkdir /var/cal-svr-base/old_csdb
   mv /var/cal-svr-base/csdb/* /var/cal-svr-base/old_csdb
   
   The old_csdb directory is a temporary location.
   
   
9. Change permissions on the temporary location.
   
   chown -R icsuser:icsgroup /var/cal-svr-base/oldcsdb
   
   
10. Migrate the Calendar Server 6.2 (Java Enterprise System 2005Q4) data using the csmigrate migration tool.
    
    cd cal-svr-base/cal/sbin
    ./csmigrate -l max /var/cal-svr-base/old_csddb /var/cal-svr-base/csdb
    
    The general syntax for csmigrate is as follows:
    
    csmigrate [-q] [-d] [-l min|max] [-b backup_dir] source_dbdir target_dbdir
    
    Command options and operands are documented in the following table.
    
    TABLE 1. csmigrate Command Options and Operands
    

    Option/Operand	Description
    -q	Specifies quiet mode, no print statements
    -d	Specifies dry run mode, no new db written
    -l min or max	Specifies log level. csmigrate creates the following log files: cal-svr-base/logs/csmigrate.log cal-svr-base/logs/csmigrateError.log
    -b backup_dir	Specifies directory to which to back up the source database. The program works on the backed-up copy to prevent any damage to the source database. The default location is source_dbdir/backup.
    source_dbdir	Directory where pre-migration database files are located.
    target_dbdir	Directory where pos-tmigration files will be written

    
    If you choose an arbitrary target_dbdir rather than /var/cal-svr-base/csdb, then you have to change the value of the caldb.berkeleydb.homedir.path property in the Calendar Server configuration file to point to that location.
    
    Note: If the csmigrate command fails on the Solaris 10 platform, set the library path to null when running the command:
    
    LD_LIBRARY_PATH= ./csmigrate ...
    

11. Restart the Calendar Server that was stopped in the earlier step.
    
    
    cal-svr-base/cal/sbin/start-cal
    
    

To Upgrade From Calendar Server 6.2 on Linux

The following procedure applies to Calendar Server on the computer where the upgrade is taking place.

1. Obtain the required patches by using the patch numbers and RPM names from Release Notes . Use this information to obtain the version numbers for the RPM.
   
   Patches can be downloaded to /tmp from: http://sunsolve.sun.com
   
   
2. Log in as root or become superuser.
   
   su -
   
   
3. Stop Calendar Server if it is running.
   
   cal-svr-base/sbin/stop-cal
   
   
4. If you have not already done so, synchronize all shared components to Release 6.
   
   See Upgrade Calendar Server Dependencies.
5. Remove the 6.2 calendar-api package
   
   rpm -e sun-calendar-api-6.2-10.28
   Note: The version number on the package name might be different, depending on the version of calendar patch installed. Confirm the package name to be deleted by using rpm -qa | grep sun-calendar
   
6. Apply the core and calendar-api in the following order. (The following *rpm files are an example. Use the *rpm files that came with the patch download.)
   
   rpm -Fvh sun-calendar-core-6.3-7.03.i386.rpm
   rpm -i sun-calendar-api-6.3-7.03.i386.rpm
   
   
7. Confirm that the patch upgrades were successful:
   
   rpm -qa | grep sun-calendar
   
   The new version numbers of the RPMs in Step 5 should be returned.
   
   
8. Reconfigure Calendar Server.
   cd cal-svr-base/sbin
   ./csconfigurator.sh
   
   If the Calendar Server 6.2 or earlier Calendar Server installation had been configured in non-hosted domain (legacy) mode, the configurator offers the choice of either staying in that mode or switching to hosted domain mode, which is the default for Calendar Server 6.3 with the latest patches. Switching to hosted domain mode is not reversible.
   
   The csconfigurator command is documented in the Calendar Server Administration Guide .
   
   
9. Move Calendar Server data files to a temporary location.
   
   mkdir /var/cal-svr-base/oldcsdb
   mv /var/cal-svr-base/csdb/* /var/cal-svr-base/oldcsdb
   
   where oldcsdb is a temporary location.
   
   
10. Change permissions on the temporary location.
    
    chown -R icsuser:icsgroup /var/cal-svr-base/oldcsdb
    
11. Migrate the Calendar Server 6.2 or earlier data by using the csmigrate migration tool.
    
    cd cal-svr-base/sbin
    ./csmigrate -l max /var/cal-svr-base/old_csddb /var/cal-svr-base/csdb
    
    The general syntax for csmigrate is as follows:
    
    csmigrate [-q] [-d] [-l min|max] [-b backup_dir] source_dbdir target_dbdir
    
    Command options and operands are documented in Table 1, shown previously.
    
    
12. Restart the Calendar Server that was stopped in Step 3.
    
    cal-svr-base/sbin/start-cal

Verifying the Upgrade

You can verify the upgrade of Calendar Server by running the following commands:

Solaris: cal-svr-base/cal/sbin/csversion

Linux: cal-svr-base/sbin/csversion

See the Release Notes for the appropriate version values.

Upgrading Calendar Server With HA

Calendar Server instances running in a cluster environment must share the same configuration. Ensure that the config directory is mounted on the node that you are upgrading. Apply Calendar Server upgrade patches to each of the instances as described previously. No reconfiguration is required.

Calendar Server Backoff

To roll back to the previous version of Calendar Server, install a fresh copy of the old version of Calendar Server and perform a csrestore on the database you backed up prior to starting the upgrade.

Commpkg Upgrade Usage

The commpkg upgrade command enables you to upgrade the Communications Suite products and shared components. It is one of the commands available with the Communications Suite installer, commpkg.

This command upgrades the Communications Suite components' installation bits on your machine, but it does not configure these components. To configure the components after installation, see Initial Configuration.

For information about upgrading, see the Communications Suite 6 Upgrade Guide.

For information about the commpkg general syntax and options, see

• Communications Suite Installer: General Syntax and Commands

For information about the other commpkg commands and their options, see

• commpkg install Usage
• commpkg uninstall Usage
• commpkg info Usage

Commpkg Upgrade Command: Syntax

Using the installroot|name Command-Line Argument

If you specify installroot|name on the command line, it specifies an alternate root to use for the upgrade. That is, it is equivalent to specifying the --altroot and --installroot options.

If you specify the name command-line argument, it must exist in the software list. If it is not, an error is returned. The name is looked up in the software list and is used for the corresponding installroot.

For details about these options, see Commpkg Install Command: Options.

Commpkg Upgrade Command: Options

The following options are used by the commpkg upgrade command:

commpkg upgrade options	Description
--excludeOS	Do not apply Operating System patches during product upgrade
--excludeSC	Do not install, upgrade, or patch any Shared Components
--acceptLicense	Accept the license conditions in the LICENSE.txt file
--altroot [name]	Specify an alternate root directory during a multi-host installation. The INSTALLROOT (the top level installation directory for all products and shared components) will be the alternate root. If you specify a name, it will be a friendly name associated with the altroot that will be registered in the software list. The name option is supported on Solaris only (not on Linux). You can use this option to install multiple instances of Communications Suite products on the same host or Solaris zone. You use this option to perform a side-by-side upgrade of Communications Suite products.
--distro path	Specify the path to packages/patches for the products Default: Location of commpkg script
--installroot path	Specify the path of INSTALLROOT, the top level installation directory for Communications Suite products and shared components. Default INSTALLROOT on Solaris and Linux: opt/sun/comms The subdirectories for individual Communications Suite products are installed under the INSTALLROOT. For example, Messaging Server (32-bit) software is installed by default in opt/sun/comms/messaging.
--silent INPUTFILE	Run silent upgrade, taking the inputs from the INPUTFILE and the command line arguments. The command line arguments override entries in the INPUTFILE. Upgrade proceeds without interactive prompts. Use --dryrun to test silent upgrade without actually installing the software. When running a silent upgrade, you must use the --acceptLicense option in the command line or set ACCEPTLICENSE=YES in the INPUTFILE. Specify NONE for INPUTFILE if you want to run in silent mode without using an input file. When you specify NONE, the upgrade uses default values. For more information about running a silent upgrade, see Upgrading Communications Suite in Silent Mode.
--dry-run or -n	Does not upgrade Communications Suite components. Performs checks. This option creates a silent upgrade file in the /tmp directory.
--upgradeSC [y|n]	Indicate whether or not to upgrade shared components as required. Note: If this option is not specified, you will be prompted for each shared component that needs to be upgraded. Default: n Caution Upgrading shared components is irreversible. However, if you do not upgrade required shared components, products might not work as designed. The --excludeSC flag has precedence over this flag.
--auditDistro	Audits the distribution to verify that the required patches and packages are present and that the packages have the correct versions. Compares the installed distribution to the product files internal to commpkg.
--pkgOverwrite	Overwrite the existing installation package. You might use this option when you are installing a shared component in a global zone where either the shared component does not exist in a global zone, or the shared component exists in the whole root zone. The default is not to override the existing package. In general, shared components should be managed in the global zone.
--components comp1 comp2 ...	Specifies the Communications Suite component products to be upgraded. Separate each component product with a space. (Thus, the list is a space-delimited set.) To specify each component product, use the mnemonic associated with that product. For example, Messaging Server (32-bit) uses MS, Messaging Server (64-bit) uses MS64, Calendar Server uses CS, and so on. To display a list of the mnemonics for all the component products, use the commpkg info --listpackages command.
--usePkgUpgrade	For Communications Suite products, if the upgrade can be performed by using a patch or an in-place package upgrade, this option uses the in-place package upgrade. The default is to use a patch to upgrade, if possible. Note: patches are only used on Solaris.

commpkg upgrade Sample Session

Here is a sample session of commpkg upgrade

Communications Express 6.3 Upgrade

This document provides information on upgrading to Communications Express 6.3, and rolling back to the previous version of Communications Express.

This document includes the following sections:
Upgrading to Communications Express 6.3
Upgrading Shared Components
Migrating Configuration Data
Adopting the Best Upgrade Strategy to Minimize Downtime, Cost, and Complexity
Rolling Back to the Legacy Communications Express Version

Upgrading to Communications Express 6.3

The upgrade procedure is same as upgrading from an earlier version of Communications Express to Communications Express 6.3.
If you are upgrading from 6.2 or earlier to 6.3, refer to Chapter 6, Upgrading Communications Express of the Sun Java Communications Suite 5 Upgrade Guide .

You can directly upgrade to Communications Express 6.3 from Communications Express 6.2 or earlier by applying the patch 21 on top of Communications Express 6.2. You can upgrade from Communications Express 6.2 to Communications Express 6.3 (Communications Suite 5/Communications Suite 6) or Communications Suite 5 (any Communications Express 6.3) to Communications Express 6.3 patch 21.

Upgrading Shared Components

It is generally recommended that all Communications Suite components on a computer system (and in a computing environment) be upgraded to Communications Suite 6. However, Communications Express has hard upgrade dependencies only on the following shared components:

• Messaging Server 7.0 (7.0-0.03)
• Calendar Server 6.3 (6.3-7.03)
• Directory Server Setup (Comms DSSetup) 6.4 (6.4-1.04)

Upgrading other Communications Suite 5 product components, on which Communications Express depends, is therefore optional.
Communications Express 6.3 supports Application Server 9.1.
For information about upgrading shared components, see:

• Messaging Server 7.0 Upgrade
• Calendar Server 6.3 Upgrade
• Upgrading comm_dssetup.pl

For more information about Communications Suite 6 software dependencies, see Requirements for Communications Suite 6 .

Migrating Configuration Data

Migrating the configuration data from Communications Suite 5 to Communications Suite 6 is same as migrating from previous versions to Communications Suite 5. For more information, refer to step7 under Upgrade Procedure (Solaris) in Upgrading Communications Express .

Adopting the Best Upgrade Strategy to Minimize Downtime, Cost, and Complexity

You can adopt the following strategies to minimize cost, downtime, and complexity:

In-place upgrade

The binaries of the old version are replaced with the binaries of the new version.

This is the normal upgrade procedure as explained in Chapter 6, Upgrading Communications Express of the Sun Java Communications Suite 5 Upgrade Guide .

Side-by-side same host upgrade

The new software version is installed on the same machine as the old version with both operating simultaneously. After the new version is configured and tested, you can switch over to the new version.

For side-by-side same host upgrade:

1. Install fresh version of Communications Express on the same machine, which hosts the older version, using commpkg install --altroot.
2. Run the product specific utility (or use manual steps) to move config/data

   patch-config/install-newconfig
   

   
   

3. Stop the old server and start the new one.

Co-existent upgrade

Existing services remain online while a new environment on separate hardware is constructed and users are carefully migrated to the new system after testing.

For co-existent upgrade:

1. Check if the hardware is ready.
2. Install latest version of Communications Express and all dependent products on a new machine using commpkg install.
3. Configure Communications Express manually on the machine. It is same as cloning the configuration of legacy machine on the new machine.
4. Run the product specific utility (or use manual steps) to move config/data

   patch-config/install-newconfig
   

   
   All the above upgrade strategies may be performed. But Co-existent Upgrade Strategy is the safest and most secure. It minimizes or even eliminates user downtime.

Rolling Back to the Legacy Communications Express Version

To roll back from Communications Express 6.3 to the older configuration, refer to Rolling Back the Upgrade .

Upgrading to Sun Java System Connector for Microsoft Outlook 7.3

This document describes how to upgrade from Connector for Microsoft Outlook 7.1 and 7.2 to Connector for Microsoft Outlook 7.3.

This document includes the following sections:

• Upgrading to Sun Java System Connector For Microsoft Outlook 7.3
• Upgrading Shared Components
• Rolling Back to Previous Version

Upgrading to Connector for Microsoft Outlook 7.3

This section explains how you can upgrade from Connector for Microsoft Outlook 7.1 to Connector for Microsoft Outlook 7.3.
Before you upgrade, as a prerequisite, set the Default Mail Client as Microsoft Outlook. For information on setting the default mail client, see Designating Outlook as Default Mail Client.

Upgrading to Connector for Microsoft Outlook 7.3 is a two step process.

Step1: Upgrading Sun Java System Connector for Microsoft Outlook Deployment Configuration Program

1. Double-click setup.exe from the Sun Java System Connector for Microsoft Outlook 7.3 package.
2. Choose the preferred language from the drop-down list in the Install/Upgrade wizard.
   The system checks if you wish to upgrade the Sun Java System Connector for Microsoft Outlook Deployment Configuration Program.
3. Click Yes to confirm or No to exit.
   The wizard starts the installation.
4. Click OK.

Step2: Upgrading User Profiles

1. Invoke Sun Java System Connector for Microsoft Outlook Deployment Configuration Program from the desktop.
2. Clear the Create/convert/upgrade user profile option in the Processes tab.
3. Select the Install or upgrade Sun Java System Connector for Microsoft Outlook option.
4. Click File and save it as filename.ini.
   The Connector for Microsoft Outlook Deployment Configuration Program creates an executable with the configuration file(.ini) you created.
5. Run the executable to start the upgrade:

   C:\Program Files\Sun\Deployment Configuration Program\Packages\filename.exe
   

   The Sun Java System Connector for Microsoft Outlook Setup Wizard is displayed.

6. Click Next to start upgrading the user profiles.
7. Click Exit to close the window.
   The user profiles are now upgraded.

Upgrading Shared Components

The following table lists the possible combinations of current versions of components that are either required or optional for Sun Java System Connector for Microsoft Outlook 7.3.

Communications Suite Component Requirements for Sun Java System Connector for Microsoft Outlook 7.3

Note Calendar Server customers who have deployed previous versions of Sun Java System Calendar Server need to engage with Sun Professional Services to enable their data to be converted and migrated to the new format. A Sun Professional Services offering is available. This migration is required for the use of Outlook, and is necessary because of the underlying changes in the storage and management of recurring events. No migration service is required for new customers of Calendar Server 6 2004Q2 minimum.

Communications Suite 6 is compatible with Sun Java System Connector for Microsoft Outlook 7.3.

For more information on upgrading the Communications Suite Components, see Communications Suite Upgrade Guide

Rolling Back to Previous Version

You cannot roll back to the previous version of Sun Java System Connector for Microsoft Outlook. You can uninstall the current version by using Add/Remove Programs from the Control Panel, and then install the required version.

For information about installing Sun Java System Connector for Microsoft Outlook 7.3, see the Connector For Outlook Installation Guide .

Upgrading Delegated Administrator

Communications Suite Release 6 includes the same release of Delegated Administrator as Communications Suite Release 5 (6.4), but it incorporates a newer patch version. If you have the original Release 5 version of Delegated Administrator, you must patch upgrade to patch -18 or later to operate with the other Communications Suite 6 products.

If you are running Delegated Administrator 6.2 or later, run the commpkg upgrade command to upgrade to the latest version of Delegated Administrator.

For upgrading versions earlier than 6.2, refer to the Sun Java Communications Suite 5 Upgrade Guide, Upgrading Delegated Administrator.

After upgrading (with either patch or commpkg upgrade) Delegated Administrator needs to be re-configured by running config-commda.

Preserving Customized Data When You Upgrade Delegated Administrator

If you are upgrading to this release of Delegated Administrator from an earlier release, you might have to perform the following tasks before you configure Delegated Administrator with the config-commda program:

• Preserving an Existing Customized Configuration
• Upgrading Customized Service Packages in Delegated Administrator 6.4 (if you are upgrading from Delegated Administrator 6.3)

Preserve an Existing Customized Configuration

This section concerns you only if you previously have installed and configured Delegated Administrator and have customized the Delegated Administrator configuration.

If you have a customized configuration and you rerun the Delegated Administrator configuration program, config-commda, the properties in the configuration files are reset to their default values. These files are listed below, in Delegated Administrator Properties Files.

For information about how you can customize Delegated Administrator, see Chapter 4, "Customizing Delegated Administrator," in the Sun Java System Delegated Administrator 6.4 Administration Guide.

You should preserve your customized configuration before you run Delegated Administrator configuration (config-commda) for any reason, including:

• Upgrade Delegated Administrator
• Patch upgrade of Delegated Administrator
• Rerun the Delegated Administrator configuration program for any other reason.

Delegated Administrator Properties Files

Delegated Administrator installs the following properties files:

• Delegated Administrator utility
  • cli-usrprefs.properties
    Location: da-base/data/config
• Delegated Administrator console
  • daconfig.properties
  • logger.properties
  • Resources.properties
  • Security.properties
    
    For the default location of the Delegated Administrator console files, see Original (Standard) Locations of the Configuration Files| in the Sun Java System Delegated Administrator 6.4 Administration Guide.
• Delegated Administrator server
  • resource.properties
    
    For the default location of the resource.properties file, see Original (Standard) Locations of the Configuration Files in the Sun Java System Delegated Administrator 6.4 Administration Guide.

To Preserve an Existing Customized Configuration

1. Back up the properties files you have customized.
   For a list of the properties files, see Delegated Administrator Properties Files.
   
   
2. Run the config-commda program, as described in the following sections.
   The remaining steps use the resource.properties file as an example. Repeat these steps for each file you have customized.
   
   
3. Edit the new resource.properties file created by the config-commda program, as follows:
   1. Open the new resource.properties file.
      
   2. Open your back-up copy of the resource.properties file.
   3. Locate the properties that were customized in the back-up copy. Apply the customized values to the corresponding properties in the new resource.properties file.
      Do not simply overwrite the new resource.properties file with the entire back-up copy. The new file may contain new properties created to support this release of Delegated Administrator.
      
      
4. Redeploy the edited resource.properties file to the Web container used by the Delegated Administrator server.
   
   Before the change can take effect, you must run the script that deploys the customized resource.properties file to your Web container.
   
   For instructions on how to deploy a customized properties file to a particular Web container, see To Deploy a Customized Configuration File in the Sun Java System 6.4 Administration Guide.

Upgrading to Instant Messaging 7.3

This section describes how to upgrade Instant Messaging 7.2 to 7.3 using commpkg upgrade. If you are upgrading from 7.1 or earlier, refer to the Chapter 7, Upgrading Instant Messaging of the Sun Java Communications Suite 5 Upgrade Guide to upgrade to 7.2, then return here to upgrade to 7.3.

Note Sun Convergence requires Instant Messaging 7.3.

Before doing an upgrade, install the required Communications Suite 6 software dependencies. See Requirements for Communications Suite 6

This document contains the following sections:

Upgrading Instant Messaging Servers

Use the following procedures to upgrade each Instant Messaging 7.2 host in your system. The process for upgrading multiplexors and servers is the same and should only take a few minutes. Note that this procedure automatically copies the 7.2 configuration and data (example: notifications, alerts, conversations and so on) to the 7.3 version. If Instant Messaging is configured to provide email notifications, Calendar alerts or Access Manager policy features (authenticating or Single-sign on), this configuration data is migrated so that these features remain in upgrading to 7.3.

1. Inform users that server will go down for a specific time period.
2. Stop the IM server
   im_svr_base/sbin/imadmin stop
   
3. Run compkg upgrade
   Make sure to say Yes when the installer asks to upgrade IM API
   
4. Run im_svr_base/html/redeploy
   
5. Restart the server
   im_svr_base/sbin/imadmin start
   
6. Run the configurator.
   For the new features in 7.3 to work you must run the configurator after upgrading. The upgrade process will not enable audio chat, nor will it deploy the IMPS gateway without running the configurator and choosing Client Components. See Instant Messaging 7.3 Initial Configuration .

Note that old configuration files will be backed up in the im_svr_base/config directory, with the name suffixed with -pre73. For example, the old iim.conf will be backed up as iim.conf-pre73. This file can be used to roll back to the previous working version in case of problems.

To Roll Back to the Legacy Instant Messaging Version

If the upgrade fails and you need to go back to the previously working version, use the following procedure.

1. Stop the server
   
2. Get the old configuration files saved when you did the compkg upgrade
   
3. Remove the new (7.3) packages
   commpkg uninstall will uninstall Communications Suite products that are installed.
   To uninstall just the Instant Messaging packages, use the following command:
   commpkg uninstall --components=IM --silent=NONE
4. Install the old (7.2) packages
5. Replace the old configuration files with their correct names (that is, rename iim.conf-pre73 to iim.conf)
   
6. Run im_svr_base/html/redeploy
7. Start the server
   im_svr_base/sbin/imadmin start

Upgrading Messaging Server 6.x to Messaging Server 7.0

Note: If you are upgrading from Messaging Server 5.2, refer to Coexistent Upgrades From iPlanet Messaging Server 5.2 for additional information. You may want to read this article as it also provides good general information for any upgrade.

This document describes the three Messaging Server upgrade strategies used to upgrade individual hosts within a deployment. This document assumes you have chosen a target deployment, and have developed an architectural design and deployment plan for your target deployment.

Messaging Server may have multiple back-end message stores, multiple webmail servers, front-end MMPs and MTA relays. Like all upgrades, you simply upgrade host by host. The major steps for upgrading a Messaging Server deployment are as follows:

• Define your upgrade target and the required products and components for that target.

• Design and Plan Your Messaging Server Architecture and Topology. Refer to Convergence Deployment Planning and Communications Suite 6 Installation Guide for details on deploying Sun Convergence into your current deployment. In addition, although you may be satisfied with your current Messaging Server Architecture and Topology, upgrading can provide the opportunity to redesign your deployment for more optimal performance. Refer to the Sun Java Communications Suite 5 Deployment Planning Guide for details.

• Select the sequence of upgrading Individual Messaging Server Hosts. This includes upgrading things like message store servers, proxies, webmail servers, front-end relays.

• Choose a Messaging Server Upgrade Strategy for Each Host. Three Messaging Server upgrade strategies offer choices that strike a balance between system downtime, cost, simplicity and risk. Strategies are chosen for each host, and different strategies can be used on different hosts within a Messaging Server deployment.

This document focuses on providing instructions for upgrading single hosts, and contains the following sections:

Technical Features Supporting Messaging Server Upgrade

The following features support Messaging Server Upgrade:

• Mailbox migration is done using imsbackup/imsrestore. See Migrating User Mailboxes to a New System. These commands support moving mailboxes from old message store versions to new ones (including when the message store database format changes e.g. from MS 32bit to MS 64bit). They also support moving mailboxes from new message store versions to old ones for back out purposes.
• In-place Upgrade (see below) supports changing the old mailbox format to the new format, but it does not support going from the new format back to the old. You cannot back out from new data format to old data format using the In-place Upgrade Strategy. The conversion is done "on-the-fly" as mailboxes are accessed.
• Migrating the Messaging Server configuration from the old system to the new system is done using migrate-config
• Alternative Root install is supported. See Performing Multiple Installations with an Alternate Root
• Upgrade is done using commpkg upgrade.

Messaging Server Upgrade Strategies

Messaging Server supports three upgrade strategies for individual hosts that provide a balance between downtime, risk of extended downtime, complexity, and potential hardware costs. The three upgrade strategies are:

• In-place Upgrade. The binaries of the old version are replaced with the binaries of the new version on the same host.
• Side-by-side Upgrade on the same host. The new software version is installed on the same machine as the old version in a different directory. After the software configuration is migrated to the new version, you switch the deployment over to the new version.
• Coexistent Upgrade. Existing services remain online while a new host on separate hardware is constructed.

The strategy chosen for any particular host may differ. For example, you may wish to use an in-place or side-by-side upgrade on your front-end servers--relays, MMPs, webmail servers, but you may wish to do a coexistent upgrade on your message stores.

Warning: There is a data format change in the message store for MS7.0. Coexistent Upgrade is recommended to facilitate backout.

The strategy you chose will also depend upon the version you currently have installed and whether you are using 32 or 64-bit Messaging Server product. The issues and compatibilities are described below.

Table 1. Upgrading to Messaging Server 7.0 32-bit

Table 2. Upgrading to Messaging Server 7.0 Upgrade 64-bit

Using the Coexistence Strategy to Upgrade Messaging Server

The Coexistence Migration Strategy is the safest and most secure method of upgrading. It also has the lowest downtime of the three upgrade strategies. In the coexistence model, existing services remain online while you construct a new target host (or entire Messaging Server environment) on new hardware or in a Solaris whole root zone on the existing hardware. After the new host/environment is established, you can migrate a small number of friendly users to the new system to verify operations and administrative procedures. For a certain period both systems are accessible to user traffic. This is called a coexistence phase. Messaging access is not disrupted and proceeds invisibly to users. When all users are migrated to the new environment, you can decommission your legacy deployment. This phased approach ensures that the new system is fully prepared to handle production users before making the full migration.

NOTE: Read Coexistent Upgrades From iPlanet Messaging Server 5.2 for very useful information on coexistent upgrades.

Advantages and Disadvantages of Coexistence Migration:

• Service downtimes are usually rare and short. There is less danger that they will be longer than the off-line windows imposed by service level agreements.

• Allows a gradual adoption of the new software so that you can gain confidence by trying it out with a small group of sympathetic users before migrating production users.

• The risk of upgrade failure is mitigated by the fact that your legacy system remains fully functioning throughout the upgrade process.

• Since the new system is built alongside a functional old one, there is no need to install or modify anything on the working legacy machines. This is an advantage as there is always a natural reluctance to modify or reconfigure a working legacy system in significant ways.

• Coexistence is the safest upgrade model and has the least amount of user downtime.

• Simpler back off procedure. Anytime you upgrade software, you need to make provisions for backing off from the new system to the old system in case of failure. Other upgrade models may require that you backup and turn off the old system, install, configure and migrate to the new system. Only when you switch on the new system do you know if the upgrade succeeded. If it turns out, that it did not, then you may have to use your back off plan to put everything back into place. A coexistence migration is much simpler as a working legacy system is already in place.

• User data, such mailboxes, must be moved from one host to another.

• May require extra hardware to set up a parallel system. (This may be mitigated by upgrading legacy machines after they are no longer used.)

Specific Steps for Upgrading Messaging Server Using the Coexistence Model

1) Make sure your hardware is installed as per the deployment plan created from the Convergence Deployment Planning and Sun Java Communications Suite 5 Deployment Planning Guide . See also the Requirements for Communications Suite 6.

2) Install new version of Messaging Server in the proper sequence on new machine, using commpkg install.

3) Configure the Messaging Server. This must be done manually. Basically you must clone the legacy machine's configuration to this new machine.

4) If you are doing a coexistent migration on a message store, migrate user mailboxes (a few at a time) to the new machine. See Migrating or Moving Mailboxes to a New System. Details on message store internals can be found in Upgrading the Message Store.

Using the Side-by-Side Strategy to Upgrade Messaging Server

In this model, the new software version is installed on the same machine as the old version. After the configuration is migrated to the new version, you can switch over to the new version. This upgrade strategy is new with Communications Suite 6. The basic steps are as follows:

• Install Messaging Server 7.0 side-by-side on the same machine with Messaging Server 6.x using the commpkg install command.
• Back up configuration and mailbox data just in case a back out is required. For the configuration data, simply back up the configuration directory. For mailbox data you can do a snapshot or an imsbackup.
• Migrate the configuration from Messaging Server 6.3 to 7.0 using the migrate-config utility.
• Startup MS 7.0

Advantages and Disadvantages of Side-by-Side Messaging Server Migration

• Second best minimal downtime.
• Second best in backout.
• Doesn't require extra machine
• Does require different directory location for fresh install. (Don't want to be working the old version.)
• Typically does not involve moving the mailboxes. New version just "points" to the mailboxes and mailbox conversion to the new version is automatic and transparent.
• Backout is problematic because mailbox format changes. Simply stopping the new version and starting the old version will not work.
• The only advantage of side-by-side over in-place is that the binaries of the old version remain intact on the system so you don't have to reinstall and reconfigure in the case of a back out.

Specific Steps for Upgrading Messaging Server Using the Side-by-side Migration Model

1. Backup the message store. This can be done using volume snapshot of the file system, or doing an imsbackup and imsrestore.
   
   
2. Install the new version of Messaging Server on the same system as your previous version of Messaging Server, but in a different directory (for example, in this procedure, /opt/sun/comms/messaging7.0/).
3. To migrate the configuration and message store data from the previous version of Messaging Server, run the migrate-config (migration configuration) utility:
   
   /opt/sun/comms/messaging7.0/sbin/migrate-config old-msg-svr-root
   
   For example:
   
   /opt/sun/comms/messaging7.0/sbin/migrate-config /opt/SUNWmsgsr
   
   
4. Run /opt/sun/comms/messaging7.0/sbin/patch-config.
5. Run /opt/sun/comms/messaging7.0/sbin/install-newconfig.
6. To back out the migration, run /opt/sun/comms/messaging7.0/sbin/migrate-config -u /opt/SUNWmsgsr, where -u is the undo flag.

Next Steps

• Once you complete the migration, stop using the old server-root directory:
  • Update their PATH and any scripts referencing the old server-root location.
  • If you are using Legato Networker, be sure to update the server-root location in the configuration.
  • Replace the server-root location with the server-root binary location.

• Start the new server with the following command:
  /opt/sun/comms/messaging64/sbin/start-msg

• If you need to back out the migration, use the ---u (undo) flag:
  /opt/sun/comms/messaging64/sbin/migrate-config ---u old-base-dir (where old-base-dir is the old server-root) directory.

• To restart the old Messaging Server, use: old-base-dir/sbin/start-msg

• Uninstall the old version Of Messaging Server when you are satisfied with the performance of the new one. commpkg uninstall

Backing Out of a Side-by-side Messaging Server Upgrade

Ideally you could just stop the new version and start the old version up and your back out recovery would be complete. However, because there is a mailbox database format change between pre-7.0 and 7.0 Messaging Servers, this won't work. To back out, you need to restore of the message store. This can be done by reinstalling the volume snapshot of the file system, or doing an imsrestore on the backed up message store.

In either case, there is a potential of losing data as mail comes in during the recovery period. For the most part, back out is considered a disaster recovery operation. Back outs are done immediately after major unacceptable problems are found in the upgrade. Thus volume snapshots are quite acceptable as a back out plan.

The basic procedure is as follows:

• Stop new version.
• Restore mailbox data
• Start old version.

Using the In-Place Upgrade on Messaging Server

In this method you simply replace the old server binaries with the new server binaries on the same machine using the commpkg upgrade command. This command removes the old packages and installs the new ones.

Advantages and Disadvantages of In-place Messaging Server Upgrade

• Simplest. One command installs the old packages and removes the new packages. This command migrates and upgrades configuration.
• Requires least amount of extra disk space.
• Messaging Server stays in the same disk location
• Has the most downtime
• Back out is complicated. Requires old product version be available. Note that if you do a mailbox data restore, then new messages that arrived since that backup may be lost.
• This method is probably best for evaluators/testers/developers.
• Useful for upgrading Messaging Servers configured without the message store. For example, front-end relays and webmail servers.

Specific Steps for Using In-Place Upgrade on Messaging Server

• run commpkg upgrade and select Messaging Server
  • it stops the servers
  • removes the old version
  • installs the new version
  • performs migration of configuration and mailbox data

For information about using the commpkg upgrade command, see commpkg upgrade Usage. Here's is a commpkg upgrade sample session.

Upgrading to Calendar Server 6.3 for Convergence in an HA (High Availability) Environment

Upgrading Calendar Server in an HA environment consists of upgrading the Calendar Server software followed by the Calendar Server Sun Cluster Agent.

This document contains the following sections:

To Upgrade Calendar Server 6.3 in an Communications Suite 6 HA Environment

The following instructions describe how to upgrade Calendar Server in an HA environment. Note that this upgrade is not supported on x86 platform.

1. Disable Calendar server resource.
   # scswitch -n -j cal-server-resource
2. Run commpkg upgrade on all nodes of the cluster.
3. Update with logical host names for following properties in the ics.conf file (work around of CR#6688858)
   local.hostname = "logical-host-name"
   local.servername = "logical-host-name"
4. For each resource group non-online or non-active node (work around of CR#6688858)
   1. Mount the config directory by making the file system a global file system, or switch the resource group to non-online or non-active node.
   2. Run csconfigurator.sh -nodisplay -noconsole -novalidate
5. Enable Calendar server resource:
   # scswitch -e -j cal-server-resource

To Upgrade the Calendar Server Cluster Agent (CS_SCHA) If Cluster Nodes include Non-Global Zones

Sun Cluster recently introduced support for Solaris 10 Zones. If a machine that has non-global zones participates in a cluster, all zones on that machine must be in the cluster. Thus the Sun Cluster software and HA agents should be installed in all zones. Thus it follows that CS_SCHA should be installed in the global zone and automatically propagated into all non-global zones (i.e. don't use the -G switch to pkgadd). The CommsInstaller treats the HA agents like CS_SCHA as a product that should be propagated to all non-global zones when it is installed in the global zone. In the rare case where you have managed to install the older CS_SCHA agent in the non-global zones, then an upgrade consists of first uninstalling the older agent from all non-global zones, followed by installing the new agent in the global zone.

To verify that the older agent was installed in the global zone and automatically propagated to all non-global zones, check if SUNWscics is listed in /var/sadm/install/gz-only-packages. If SUNWscics is listed in /var/sadm/install/gz-only-packages, then simply run commpkg upgrade in the global zone. If it isn't listed, then SUNWscics is either not installed, or installed so that it is propagated to non-global zones. If this is the case, then use the following procedure:

1. Run commpkg uninstall and uninstall the CS_SCHA in every non-global zone (don't uninstall it in the global zone)
2. In the global zone, run commpkg upgrade and upgrade CS_SCHA

Upgrading Communications Suite in Silent Mode

If you run the Communications Suite installer to upgrade the products in Silent mode, you are running a non-interactive session. This is useful for upgrading multiple instances of the same software component/configuration without have to manually run an interactive upgrade on each instance. The upgrade inputs are taken from a silent upgrade file (also known as a state file), from command line arguments, or defaults.

To run a silent upgrade, follow these steps:

1. Run an interactive upgrade session. A state file similar to /var/opt/CommsInstaller/logs/silent_CommsInstaller_20070501135358 is automatically created for every run of the upgrade.
   You can create a silent state file without actually upgrading the software during the interactive session by using the --dry-run option, then modifying the state file. For example:

   # commpkg upgrade --acceptLicense --dry-run 
   

2. Copy the state file to each host machine and edit the file as needed. See Silent Mode File Format.
3. Run the silent upgrade on each host. For example:

   # commpkg upgrade --acceptLicense --silent <Input File>
   

   where Input File is the path and name of the silent state file. For example: /var/opt/CommsInstaller/logs/silent_CommsInstaller_20070501135358.

For details about the --silent option, see the silent upgrade usage in commpkg upgrade Usage.

Note Command-line arguments override the values and arguments in the state file.

About Upgrading Shared Components By default, shared components are not upgraded when you run a silent upgrade. The option to upgrade shared components in the silent state file is automatically disabled. That is, the option is set to UPGRADESC=No. This is true even if you explicitly asked to upgrade shared components when you ran the interactive upgrade that generated the silent state file. That is, you ran commpkg upgrade --upgradeSC y. The reason to disable upgrading shared components in the silent state file is this: the other hosts on which you are propagating the upgrade may have different shared components installed, or different versions of the shared components. These versions may be required for other applications running on the different hosts. Therefore, it is safer not to upgrade the shared components by default. You can upgrade shared components when you run a silent upgrade by taking either of these actions: Use the --upgradeSC y option when you run the silent upgrade. (The command-line argument overrides the argument in the state file.) Edit the UPGRADESC=No option in the silent state file to: UPGRADESC=Yes.

Silent Mode File Format

The silent mode file (also known as a state file) is formatted like a property file: blank lines begin with a number sign (#) and properties are key/value pairs separated by an equals (=) sign. You can change the following parameters:

• VERB— indicate which function to perform. For example VERB=install
  
  You can add CLI arguments described in commpkg upgrade Usage, however the —dry-run argument cannot be added to the upgrade function in the state file.
• ALTDISTROPATH— indicate an alternate distro path if —distro is not specified. For example, ALTDISTROPATH=SunOS5.10_i86pc_DBG.OBJ/release
• PKGOVERWRITE— set this flag if you want to overwrite the existing installation packages. For example, PKGOVERWRITE=YES
• INSTALLROOT— specify installation root. For example, INSTALLROOT=/opt/sun/comms
• ALTROOT— set this flag if you want to use an alternate root. For example, ALTROOT=yes
• EXCLUDEOS— set this flag if you don't want to upgrade Operating System patches. For example, EXCLUDEOS=YES
• COMPONENTS— list the components you want to upgrade.* For example:
  • COMPONENTS=MS64 for 64–bit Messaging Server.
  • COMPONENTS=MS64_L10N for localized 64–bit Messaging Server.
  • COMPONENTS=MS for 32–bit Messaging Server.
  • COMPONENTS=MS_L10N for localized 32–bit Messaging Server.
  • COMPONENTS=CS for Calendar Server.
• ACCEPTLICENSE- indicate whether or not to accept license. For example, ACCEPTLICENSE=yes.
  
  This property must be specified either in the state file or as a command line argument.
• UPGRADESC– indicate whether all shared components should or should not be upgraded without prompting. For example, UPGRADESC=no

* To display a complete list of the product names (such as MS, MS64, CS) to use with the COMPONENTS property, run the commpkg info --listPackages command. This command displays the mnemonics for each product.

Upgrading the Message Store

The document describes the data components and tools of message store, and how they affect data upgrades. The purpose of this document is to provide the technical background for upgrade planning. If you are using the upgrade procedure described in Upgrading the Messaging Server, you do not need to concern yourselves with this level of message store technical detail. However, if you need to customize your message store upgrade process, you may use this document as a guideline.

This document includes the following topics:

Architecture and Components

The diagram below shows the message store architecture and its components. See Message Store Directory Layout for a view of the message store file structure.

Full Size

Messaging Server and its message store have been around since about 1997, and for purposes of this article, it has had the following versions: 4.15, 5.x, 6.0, 6.1, 6.2, 6.3, and 7.0. During this time, there have been three mailbox versions: 1_1, 1_2 and 1_3.

The message store uses the Berkeley Database provided by Sleepycat Software and, since 2006, Oracle Corporation. The message store database files are stored in a directory called mboxlist (see Message Store Directory Layout, and so it is often called the mboxlist database.

Message store has used a number of versions of the Berkeley Database over the course of its existence. Thus, when you upgrade your message store, the Berkeley Database may also be upgraded. The database engine upgrade may have complexities and implications for the data upgrade. (Again, note that these complexities and implications are handled in the Message Store upgrade tools and instructions described in Upgrading the Messaging Server, but these details are described here for custom upgrade plans.)

The mboxlist database is stored in the BTREE database files. The BTREE database files store information about the message store users and mailboxes (see Message Store Directory Layout). The number and types of files, as well as the structure of files themselves have varied over the life of the Berkeley Database. The message store has used three different versions of the BTREE files. These are BTREE 6, 8 and 9.

The Berkeley Database is transactional, so each transaction is logged in a database log file. Database log files are used for recovery. All database changes are recorded in the database log file. When the server is crashed and restarted, it uses the log file to bring the database back to a consistent state. Before you do an upgrade, make sure you have a clean shutdown and recovery by running stored -r.

The format of the database log files has evolved over the years, and so the log files have different versions. Messaging Server has used five different log file versions: 2, 3, 8, 11, and 14.

Message Store Component Version Compatibilities

The following table contains the version number of various database components in the message store with respect to upgrade.

Generally speaking, when you upgrade the messaging server from one version to another, you also have to upgrade the components that have a different version. Certain message components are not compatible with other components. This section describe the various compatibilities and incompatibilities.

Mailbox Version Compatibilities

The message store upgrades mailboxes from version 1_1 to 1_2 and from 1_2 to 1_3 automatically. Usually, a mailbox is upgraded when the end users select their mailboxes, or when messages are delivered to the mailboxes after the message store software is upgraded. The message store checks the mailbox version in the mailbox header and upgrades the mailbox if needed.

To upgrade the mailboxes sequentially and immediately, you can run imcheck > /dev/null. imcheck opens every mailbox, which triggers the migration.

To upgrade from mail version 1_1 to 1_3 you have to use a migration tool such as imsbackup and imsrestore.

Downgrading mailbox versions is not automatic. You have to use a migration tool such as imsbackup and imsrestore to downgrade a mailbox.

Upgrading and Downgrading the Berkeley Database (BDB)

The Message Store uses a custom version of the Berkeley Database to store various data. The email messages themselves are not part of the data stored in the BDB. If the database is upgraded to a version that is incompatible with the previous version, the database files will become incompatible with older versions of the Message Store. We recommend, therefore, that you make a backup copy of the database before the upgrade in case you want to back out of the upgrade.

The primary database which needs to be backed up is located by default in the mboxlist/ directory, and consists of .db files, and log. files. The __* files are cache files for the database and do not need to be copied. A correct copy of the database ensures data is in a consistent state. The message store and utilities must be shut down. Running stored -r will make sure the cache files are synced to the database files. Both database and log files are required.

If you need to back out of a patch or update which upgrades the Berkeley Database to a version that is incompatible with previous versions and you did not make a backup, you may be able to rely on a previous database snapshot. Database snapshots are located by default in the dbdata/ directory. A valid database snapshot directory will have both a .snaptime file and a .verified file. The .snaptime file indicates if the time of the snapshot was before the upgrade. The .verified file indicates that the snapshot has been recovered, verified, and is ready to be used.

Normally when the store is brought up, the stored process replaces the mboxlist directory with any snapshots needed. In the case where you have backed out of a database upgrade, stored may not take into account that a downgrade has occurred. It may therefore be necessary to replace the valid snapshot manually. To do this, move the current database files in mboxlist/ out of the directory and move all the files from the chosen snapshot directory into the mboxlist/ directory. Be sure to move the __* cache files as well. Note that if the store is configured with store.dbtmpdir, the cache files will be in a different location.

If you have no database backup and no valid snapshots, it may be necessary to move the upgraded database out of the way, and rebuild it from scratch. Under normal circumstances, the Message Store rebuilds the database while allowing users to access their mail. Since doing this puts a heavier load on the system, you should create proper database backups instead.

Normal reparation of the database should be done after putting an older version in place by running reconstruct -m and reconstruct -r.

Some of these manual requirements might be addressed in future releases.

Note that the Berkeley database consist of a number of BTREE files, LOG files and temporary files (tmp file location is configurable with store.dbtmpdir). In order to upgrade the database, run stored -r before replacing the new libraries and binaries. Note that stored -r runs automatically during the proper upgrade process.

In the unlikely event that stored -r fails, check the store log files to determine the cause, run stored alone to perform a database recovery, and run stored -r again. In normal circumstances, this should not be a problem unless there is some underlying system problem which you should resolve before upgrading.

Database Btree File

BTREE version 8 and 9 are compatible. Upgrade is not needed.

To upgrade the BTREE files from version 6 (BDB 2.6) to a higher version, copy the database files from the old location (example: /usr/iplanet/server5/msg-store/store/mboxlist for 5.2) to the new mboxlist location (example: /var/opt/SUNWmsgsr/store/mboxlist), then run ims_db_upgrade.

Database Log Files

Database log files cannot be upgraded. When the log version changes, run the legacy version of stored -r to process the log files (recover the database) before upgrading. Do not remove the old log files.

The following message is logged when the server restart.

'Skipping log file...historic log version'

The store daemon creates a new log file with the new version.

IMAPD, MSHTTPD and Sun Convergence

Starting in Messaging Server 6.3, the webmail server (mshttpd) uses imapd to access the Message Store. imapd and mshttpd in 6.3 and 7.0 are fully compatible, so simultaneous upgrade is not required. To prevent memory problems due to redundant IMAP sessions from mshttpd, you should run with only one mshttpd process. If you serve a lot of concurrent webmail users, this might require an upgrade to 64bit so that you have enough virtual address space for the process.

Sun Convergence requires webmail server 7.0. To use Convergence, you must upgrade mshttpd to 7.0.

Upgrading From Messaging Server 32-bit to 64-bit

Run the legacy version of stored -r before upgrading the Messaging Server software from 32-bit to 64-bit.

If you run the 64-bit version, then it is more efficient to run with only one mshttpd process. See mshttpd Changes Starting with Messaging Server 6.3 for more information.

You might also want to reduce the number of imapd process. See Why Using Messaging Server 64-bit Edition Is Better.

Note The Sun Java System Messaging Server 6.3 64-bit Installation Technical Note also has information about upgrading from 32-bit to 64-bit.

Migrating from x86 to SPARC

The message store data formats are architecture dependent. You cannot transfer any data components in the matrix from one architecture to another directly. To migrate the message store from an x86 machine to a SPARC machine, use imsbackup and imsrestore to migrate the mailboxes.

stored -r

stored -r performs a final recovery and cleanly removes the database temp files to prepare the database for an upgrade.

For example:

# /opt/SUNWmsgsr/lib/stored -r
removing mboxlist environment ... done
removing lock environment ... done
removing session db ... done

Make sure stored -r completes successfully.

MS 6.2 stored -r requires the watcher process. Make sure the watcher is running when you run stored -r

stored -r is introduced in MS 6.1. For MS 6.0, use the following procedure:

# stop-msg
# start-msg store
# stop-msg
# rm ${dataroot}/store/mboxlist/__db*
# rm ${dataroot}/store/mboxlist/folderlock/*
# rm ${dataroot}lock/__db*

ims_db_upgrade

ims_db_upgrade copies the database files to a backup directory, upgrades the database files to the current version and validates the new database. If upgrade is not successful, the backup files are restored. If the database is validated, the backup files are removed.

Downgrading

Mailbox and BDB downgrade are not supported. To downgrade a message store to an older version with incompatible mailboxes or databases, you must restore the mailboxes and mboxlist database from backup.

Upgrading to Instant Messaging Server 7.3 in an HA (High Availability) Environment

Upgrading Instant Messaging Server in an HA environment consists of upgrading the Instant Messaging Server software followed by the Instant Messaging Server Sun Cluster Agent.

This document contains the following sections:

To Upgrade to Instant Messaging Server 7.3 in an HA Environment

1. Disable IM server resource
   # scswitch -n -j im-server-resource
2. Run commpkg upgrade command on all nodes of the cluster.
3. Enable M server resource
   # scswitch -e -j im-server-resource

To Upgrade to Instant Messaging Server 7.3 Sun Cluster Agent (IM_SCHA)

Run commpkg upgrade command on all nodes on the cluster.

If cluster node is a non-global zone, run commpkg upgrade in global zone as well as in non-global zones.

Upgrading to Messaging Server 7.0 in an HA (High Availability) Environment

Upgrading Messaging Server in an HA environment consists of upgrading the Messaging Server software followed by the Messaging Server Sun Cluster Agent.

This document contains the following sections:

Upgrading to Messaging Server 7.0 in an HA Environment

Each upgrade strategy requires different procedures for upgrading in an HA environment. A coexistent environment would be like a new HA installation (see Configuring Messaging Server for High Availability). Side-by-side and In-place HA upgrades are described below.

To Do a Side-by-side Upgrade to Messaging Server 7.0 in an HA Environment

1. Go to the resource group online node.
   1. Disable Messaging server resource,
      # scswitch -n -j msg_svr_resource
   2. Upgrade Messaging Server using the side-by-side strategy (see discussion here). This must be performed only on the Messaging Server resource group online node. Do not start Messaging Server yet.
   3. Run hp_ip_config command. This command is needed because Messaging Server upgrade overwrites logical IP values with local host IP values.
      # msg_svr_base/sbin/ha_ip_config
2. Switchover to other node:
   # scswitch -z -g msg_svr_resource_group -h node-name
3. Run useconfig command. This is needed if Messaging Server upgrade is from 32-bit to 64-bit, to update library path /bin/crle-64')
   # msg_svr_base/sbin/useconfig configdir
4. Change IMS_serverroot path for Messaging Server resource if new Messaging Server base directory is different from old installation.
   #scrgadm -cj msg_svr_resource -x IMS_serverroot=new_msg_svr_base
   
5. If Messaging Server Sun Cluster agent (MS_SCHA) is old (not from R6 release), then it will not work with upgraded Messaging Server. So perform MS_SCHA upgrade procedure.
   
   
6. Enable Messaging Server resource.
   
   # scswitch -e -j msg_svr_resource

To Do an In-place Upgrade to Messaging Server 7.0 in an HA Environment

An in-place upgrade is done by using the commpkg upgrade command. This command is not available for upgrading from Messaging Server 32-bit to Messaging Server 64-bit. Side-by-side upgrade supports upgrading from Messaging Server 32-bit to Messaging Server 64-bit.

1. Disable Messaging Server resource:
   # scswitch -n -j msg_svr_resource
2. Run the commpkg upgrade command on all nodes of the cluster.
3. Run the ha_ip_config command on the active node of the cluster.
   # msg_svr_base/sbin/ha_ip_config
4. Enable Messaging Server resource:
   # scswitch -e -j msg_svr_resource

Upgrading to the Messaging Server 7.0 Sun Cluster Agent (MS_SCHA)

This section provides instructions for the Sun Cluster Agent upgrade. It consists of the following sections:

To Upgrade to the Messaging Server 7.0 Sun Cluster Agent (MS_SCHA)

1. Run commpkg upgrade on all nodes on the cluster. Messaging Server should be upgraded to 7.0 before upgrading Messaging Server Sun Cluster Agent.
   
2. Enable Messaging Server resource:
   # scswitch -e -j ms-server-resource

To Upgrade to the Messaging Server 7.0 Sun Cluster Agent (MS_SCHA) If Cluster Nodes include Non-Global Zones

Sun Cluster recently introduced support for Solaris 10 Zones. If a machine that has non-global zones participates in a cluster, all zones on that machine must be in the cluster. The Sun Cluster software and HA agents should be installed in all zones, and MS_SCHA should be installed in the global zone and automatically propagated into all non-global zones (that is, don't use the -G switch to pkgadd). The Communications Suite Installer treats HA agents like MS_SCHA as a product that should be propagated to all non-global zones when it is installed in the global zone. In the rare case where you have managed to install the older pre-7.0 MS_SCHA agent in the non-global zones, then an upgrade consists of first uninstalling the older agent from all non-global zones, followed by installing the new 7.0 agent in the global zone.

To check if the older pre-7.0 agent was installed in the global zone and automatically propagated to all non-global zones, verify that SUNWscims is listed in /var/sadm/install/gz-only-packages. If it is, then run commpkg upgrade in the global zone. If it isn't listed, then SUNWscims is either not installed, or is installed so that it is propagated to non-global zones. If this is this case, use the following procedure:

1. Run commpkg uninstall and uninstall MS_SCHA in every non-global zone (don't uninstall it in the global zone)
2. In the global zone, run commpkg upgrade and upgrade MS_SCHA

To Upgrade to the Messaging Server 7.0 Sun Cluster Agent (MS_SCHA) in a Two-node Symmetric Sun Cluster HA Environment

1. Upgrade Messaging Server to 7.0 before upgrading the Messaging Server Sun Cluster Agent.
2. Make sure that the Messaging Server installation location is accessible from both nodes.
   
   This is required because a resource type upgrade command validates accessibility. For the first instance in a Symmetric Cluster setup, Messaging Server installation will be done on first node only (on a shared storage mount point). For the second instance, Messaging Server installation will be done on second node only.
3. Follow the steps mentioned in section To Upgrade to the Messaging Server 7.0 Sun Cluster Agent (MS_SCHA)

Note: If user prefers to upgrade Sun Cluster Agent (MS_SCHA) for only one instance, then follow above steps and correct the resource type version using Sun Cluster commands.