Printable Communications Suite 7 Upgrade Guide

Skip to end of metadata
Go to start of metadata
Contents

Sun Java Communications Suite 7 Upgrade Guide

This information describes the best practices for upgrading earlier versions of Communications Suite products to version 7. (For a list of those individual product version numbers see Communications Suite 7 Products and Components.)

Topics:

Terminology
In the information provided here, the term product refers to items such as Messaging Server, Calendar Server, Delegated Administrator, and Instant Messaging Server. Product components are functional parts of the products. For example, Messaging Server has message stores, relays, and messaging multiplexors. Calendar Server has front-end and back-end servers. Shared components refers to software components that are not part of Communications Suite or other support products, but are required for Communications Suite products to operate. Examples include NFS, SASL, and Java.

About the Communications Suite Upgrade Process

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

Defining Your Target Communications Suite 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 know what products and components you need to upgrade and which ones can remain as is.

The three most common Communications Suite upgrade scenarios are:

  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 and components necessary to support that feature.

    In this scenario, you simply upgrade the desired product. See the product-specific upgrade section(s)on this page.

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

  3. You want to upgrade all products and components to the latest release.

    You upgrade each product individually, host-by-host. See Requirements for Communications Suite 7.

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

Tip
Installing Only Shared Components: To install just the shared components for a component product, launch the Communications Suite installer then prefix your product selection with a tilde (~). For example, to install only the shared components for Messaging Server 64-bit, at the Product Selection prompt, you would type ~1. You can type multiple selections, separating your entries with a comma.

Determining the Sequence of Product Upgrades

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

  • 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 Update 3 Upgrade.

Upgrading Messaging Server in an HA (High Availability) Environment

See Upgrading to Messaging Server 7 Update 3 in an HA Environment.

Upgrading Calendar Server in Solaris OS

See Calendar Server 6.3 Upgrade.

Upgrading 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 8 Update 2 Upgrade.

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

See Upgrading to Instant Messaging 8 Update 2 in an HA Environment.

Upgrading Sun Convergence

To upgrade from Sun Convergence 1 Update 2 to Sun Convergence 1 Update 3, see Upgrading to Convergence 1 Update 3.

Upgrading Delegated Administrator

See Delegated Administrator 7 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 Administrator, 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 Sync

Using Sun Java System Communications Sync with Communications Suite 7 and Sun Convergence requires Sun Java System Communications Sync Version 3.1. Sync 3.1 is the same as Sync 3.0 but with additional fixes.

Upgrading Outlook Connector

See Connector for Microsoft Outlook 7.3 Update 1 Upgrade Guide.

Additional Communications Suite 7 Upgrade Information

The following information is what is linked to in the main body of this Upgrade Guide. The information is organized alphabetically by title.

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 Update 2, 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, first refer to the Chapter 5, Upgrading Calendar Server, from 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 Red Hat 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 Red Hat 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 OS 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 OS 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 has the software dependencies listed in the Release Notes . For a list of all Communications Suite requirements, see the Requirements for Communications Suite 6 Update 1.

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 Update 1 both use Calendar Server 6.3, but Communications Suite 6 Update 1has the required patches that work with Sun Convergence.

  1. Run commpkg upgrade command.

To Upgrade From Calendar Server 6.2 on Solaris OS

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

    See Communications Suite 6 Update 1 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 OS 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 Red Hat 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 OS: cal-svr-base/cal/sbin/csversion

Red Hat 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, which is available with the Communications Suite installer, commpkg, enables you to upgrade the Communications Suite products and shared components.

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

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

For information about the commpkg general syntax, other commands, and options, see:

Commpkg Upgrade Command: Syntax

commpkg upgrade [options] [installroot|name]

Using the installroot|name Command-Line Argument

Specify installroot|name on the command line to use 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 Does not apply operating system patches during product upgrade.
--excludeSC Does not install, upgrade, or patch any shared components.
--acceptLicense Accepts the license conditions in the LICENSE.txt file.
--altroot [name] Specifies an alternate root directory during a multi-host installation. The INSTALLROOT (the top-level installation directory for all products and shared components) is the alternate root.
If you specify a name, it is a friendly name associated with the alternate root that is registered in the software list. The name option is supported only on Solaris OS (not on Red Hat Linux).
You can use this option to install multiple instances of Communications Suite products on the same host or Solaris zone. You can use this option to perform a side-by-side upgrade of Communications Suite products.
--distro path Specifies the path to packages and patches for the products.
Default: Location of commpkg script
--installroot path Specifies the path of INSTALLROOT, the top-level installation directory for Communications Suite products and shared components.
Default INSTALLROOT on Solaris OS and Red Hat Linux: /opt/sun/commsThe 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 Runs 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 --dry-run 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] Indicates whether or not to upgrade shared components as required.
Note: If this option is not specified, you are 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 Overwrites 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 OS.

commpkg upgrade Sample Session

Here is a sample session of commpkg upgrade.

Upgrading to Sun Java System Connector for Microsoft Outlook 7.3 Update 1

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

This document includes the following sections:

Upgrading to Connector for Microsoft Outlook 7.3 Update 1

This section explains how you can upgrade from Connector for Microsoft Outlook 7.1 and subsequent versions to Connector for Microsoft Outlook 7.3 Update 1.
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 Update 1 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 Update 1 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
Note:
This step is not required if you are upgrading from Outlook Connector version 7.2 or later.
  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:

    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.

Upgrade Scenarios

  • If you are using Communications Express address book server and Outlook Connector for Mail Filters and Out of Office Messages, then you may follow the upgrade procedure as mentioned in Step 2.
  • If you are using Convergence's address book server and Communications Express for Mail Filters and Out of Office Messages, perform the following steps after creating the configuration file:
  1. Open the configuration (.ini) file that you created.
  2. Enter the value for Use_UWC_Url as 1.
  3. Enter the value for UWC_Url key in the following format:

    For example, the value of the key may be:

  4. Invoke Outlook Connector Deployment Configuration Program.
  5. Open the configuration (.ini) file that you modified and click File -> Save to create a new package.
  6. Click Yes when prompted to overwrite the existing package.
  7. Run the newly created package.

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

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

Product Version Communications Suite Release Comment
Messaging Server 6.3 5 Required to provide mail service
Messaging Server 7.0, 7 Update 1 6 Required to provide mail service
Calendar Server 6.3, 6.3.1 5 Required to provide calendar service
Convergence 1.0, 1 Update 1 6 Optional (Recommended).
Either Communications Express or Convergence can be used to provide address book service,
mail filters and out of office message features
Communications Express 6.3 6 Optional
Directory Server 5.2 4 Required for GAL – corporate address book service
Directory Server at least 6.0 5 (for 6.0 or higher) or
6 (6.3 or higher)
Required for GAL – corporate address book service
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 Update 1 is compatible with Sun Java System Connector for Microsoft Outlook 7.3 Update 1.

For more information on upgrading the Communications Suite 6 Update 1 Components, see Communications Suite 7 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 Update 1, see the Connector For Outlook Installation Guide .

Upgrading to Delegated Administrator 7

This chapter explains how you can upgrade to Delegated Administrator version 7. If you are running Delegated Administrator 6.4, run the commpkg upgrade command to upgrade to Delegated Administrator version 7.

For upgrading from versions earlier than 6.4, you need to upgrade to 6.4. See Sun Java Communications Suite 5 Upgrade Guide, Upgrading Delegated Administrator. Then upgrade from 6.4 to 7, using commpkg upgrade.

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:

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 Customizing Delegated Administrator in the Sun Java System Delegated Administrator 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 [ Configuration Files and Directories|CommSuite:Delegated Administrator Files and Directories] in the Sun Java System Delegated Administrator Administration Guide.
  • Delegated Administrator server
    • resource.properties
    • serverconfig.properties
      Most of the configuration related properties are moved from resource.properties to the serverconfig.properties file.


For the default location of the resource.properties file, see [ Configuration Files and Directories|CommSuite:Delegated Administrator Files and Directories] in the Sun Java System Delegated Administrator 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 Administration Guide.
If you have customized values in the resource.properties file from previous releases, ensure that the same customization is made in the new serverconfig.properties file.

Upgrading to Instant Messaging 8 Update 2

This section describes how to upgrade Instant Messaging 7.3 and later to version 8 Update 2.

Note
You can upgrade to the Instant Messaging 8 Update 2 only by using the Communication Suite installer.

This section contains the following topics:

Upgrading Instant Messaging Servers

The process for upgrading the Instant Messaging server and multiplexor is the same and should only take a few minutes. The upgrade procedure automatically copies the 7.3 configuration and data such as notifications, alerts, and conversations to version 8. If Instant Messaging is configured to provide email notifications, Calendar alerts or Access Manager policy features such as authenticating or single-sign on, the configuration data of these features are migrated to version 8.

To upgrade the Instant Messaging version, perform the following steps on an existing installation of Instant Messaging:

  1. Stop the Instant Messaging server.
    im_svr_base/sbin/imadmin stop
  2. Use the communication installer to upgrade Instant Messaging.
    ./commpkg upgrade
  3. Select the components you wish to upgrade.
  4. Restart the Instant Messaging server.
    im_svr_base/sbin/imadmin start
  5. Redeploy the Instant Messaging server by typing
    /opt/SUNWiim/sbin/iwadmin redeploy all or
    or /opt/SUNWiim/html/redeploy
    This step completes the upgrade process and redeploys all client-side components.
  6. Optional. Invoke the configure utility.
    ./configure
    Perform step 6 only if you want to configure the server-side components such as SMS, MSN, and AIM gateways.
    Note
    When you configure the server, all previous configuration is overwritten.

The old configuration files are backed up in the config directory with the string -pre8.2 suffixed to the filename. For example, the old iim.conf is backed up as iim.conf-pre8.2. This file can be used to roll back to the previous working version in case of a upgrade failure.

Rolling Back to the Legacy Instant Messaging Version

If the upgrade fails or if you need to go back to the previously working version of Instant Messaging, you can roll back to the upgrade process.

To roll back the upgrade process, perform the following steps:

  1. Stop all services.
  2. Remove the 8.0 Update 2 packages by using the pkgrm command.
  3. Install the old version of Instant Messaging, for example, version 7.2 or 7.3, by using the Communication Suite installer for that version.
    Note
    The pre-8.2 configuration files are backed up in the config directory with the string -pre8.2 suffixed to the filename. For example, the old iim.conf is backed up as iim.conf-pre8.2.
  4. Rename the old configuration files with their correct names. That is, rename iim.conf-pre8.2 to iim.conf.
  5. Restart the services.

Upgrading Messaging Server to Messaging Server 7 Update 3

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

This document focuses on upgrading single hosts and contains the following sections:

Note
If you are upgrading from Messaging Server 5.2, refer to Coexistent Upgrades From iPlanet Messaging Server 5.2 for additional information. This article provides good general information for any upgrade.

Overview

Messaging Server can 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:

  • Upgrade and run comm_dssetup.pl to the latest version before upgrading Messaging Server. Messaging 7 Update 3 requires comm_dssetup.pl 6.4p5 (6.4-5.05) at a minimum be applied to the Directory Server.
  • 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 7 Installation Guide for details on deploying Sun Convergence into your current environment. In addition, although you might 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 Communications Suite Deployment Planning Guide for more information.
  • Select the sequence of upgrading Individual Messaging Server Hosts.
    This includes upgrading components such as the message store servers, proxies, webmail servers, and 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. You choose a strategy for each host, and you can use different strategies on different hosts within a Messaging Server deployment.
    Note
    As of Communications Suite 7, Messaging Server 32-bit has been dropped on Solaris OS. Thus, if you are upgrading from Messaging Server 32-bit, you must migrate to Messaging Server 64-bit by using either the coexistence or side-by-side upgrade strategies. In particular, commpkg upgrade does not support upgrading from Messaging Server 32-bit to Messaging Server 64-bit.

Technical Features Supporting Messaging Server Upgrade

The following features support Messaging Server Upgrade:

  • You migrate mailboxes by using the imsbackup and imsrestore commands. 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, for example, from Messaging Server 32-bit to Messaging Server 64-bit). These commmands also support moving mailboxes from new message store versions to old ones for back out purposes.
  • In-place Upgrade 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 by 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 by using the migrate-config utility.
  • Alternate Root install is supported on solaris. See Performing Multiple Installations with an Alternate Root for more information.
  • In-place server upgrade is by done using commpkg upgrade.

Messaging Server Upgrade Strategies

Messaging Server supports the following three upgrade strategies for individual hosts. These strategies provide a balance between downtime, risk of extended downtime, complexity, and potential hardware costs.

  • 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 host as the old version in a different directory. After you migrate the software configuration to the new version, you switch the deployment over to the new version.
  • Coexistent Upgrade. You keep existing services online while you construct a new host on separate hardware.

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

Caution
There is a data format change in the message store starting with Messaging Server 7 (see Upgrading the Message Store ). Coexistent Upgrade is recommended to facilitate backout.

The strategy you chose also depends upon the version you currently have installed and whether you are using 32-bit or 64-bit Messaging Server product. Issues and compatibilities are described next.

Table 1. Upgrading to Messaging Server 7 Update 3 32-bit (Red Hat Linux only)

From Online/Coexistence Side-by-Side Migration In-place Upgrade via rpm -U?
6.1, 6.2, 6.3 (32-bit) (R2 through R5) Yes (recommended for store) Yes (alternative for store)
Note: No back out to old data format.
Yes (recommended for MTA relay, MMP, and webmail server)
7, 7u1, 7u2 (R6, R6u1, R6u2)
Yes
Yes
Yes

Table 2. Upgrading to Messaging Server 7 Update 3 64-bit (Solaris OS Only)

From Online/Coexistence Side-by-Side Migration In-place Upgrade via pkgadd/pkgrm or Patch?
5.2
Yes (recommended for all components)
Yes (alternative for all Messaging Server components)
Note: Messaging Server 5.2 did not use SVR4 packaging, so this is just a fresh install.
No
6.0,6.1,6.2,6.3 (32-bit) (R1 through R5) Yes (recommended for store) Yes (alternative for store) No
6.3 (64-bit) (R5) Yes (recommended for store) Yes (alternative for store) Yes: pkgadd/pkgrm (recommended for MTA relay, MMP, and webmail server)
7, 7u1, 7u2
(32bit)
Yes Yes No
7, 7u1, 7u2 (R6, R6u1, R6u2)
(64bit)
Yes
Yes
Yes: pkgadd/pkgrm or patchadd
Note
When upgrading/migrating between SPARC and x86 hardware, you need to use the Online/Coexistence strategy. Also, see Migrating from x86 to SPARC.

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 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.
  • Because the new system is built alongside a functional old one, you do not 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 might require that you back up 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 might 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.
  • You must move user data, i.e mailboxes, from one host to another, typically using imsbackup/imsrestore.
  • Might require extra hardware to set up a parallel system. (This can 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 that your hardware is installed as per the deployment plan created from the Convergence Deployment Planning and Communications Suite Deployment Planning Guide. See also the Requirements for Communications Suite 7.
  2. Install new version of Messaging Server in the proper sequence on new machine, by using the commpkg install command.
  3. Configure Messaging Server.
    You must do so 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, you install the new software version on the same machine as the old version. After migrating the configuration to the new version, you can switch over to the new version. This upgrade strategy is new starting with Communications Suite 6. The basic steps are as follows:

  1. Install Messaging Server 7 Update 3 side-by-side on the same machine with your earlier version of Messaging Server by using the commpkg install command.
  2. 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 use the imsbackup command.
  3. Migrate the configuration from Messaging Server to 7 Update 3 by using the migrate-config utility.
  4. Start Messaging Server 7 Update 3.

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

  • Second best minimal downtime.
  • Second best in backout.
  • Does not require extra machines
  • Does require different directory location for fresh install. Any custom scripts that reference the install location has to be modified.
  • 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 if there are 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 do not 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. Back up the message store.
    You can use either the volume snapshot of the file system or perform 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/messaging7u3/).
  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/messaging7u3/sbin/migrate-config old-msg-svr-root. (In the example below old-msg-svr-root is /opt/SUNWmsgsr)
    For example:
    /opt/sun/comms/messaging7u3/sbin/migrate-config /opt/SUNWmsgsr
    
  4. Run the following command:
    /opt/sun/comms/messaging7u3/sbin/patch-config
    
  5. Run the following command:
    /opt/sun/comms/messaging7u3/sbin/install-newconfig
    
  6. To back out the migration, run the following command:
    /opt/sun/comms/messaging7u3/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 PATH and any scripts referencing the old server-root location.
    • If you are using EMC Networker (formerly 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/messaging7u3/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-msg-svr-root (where old-msg-svr-root is the old server-root) directory.
  • To restart the old Messaging Server, use: old-msg-svr-root/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-version 7 and version 7 Messaging Server, this does not work. To back out, you need to restore the message store either by reinstalling the volume snapshot of the file system, or by performing 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. Backouts 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 by using the commpkg upgrade command. This command removes the old packages and installs the new ones. For details about this command, see commpkg upgrade Usage.

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 (no tweaking of custom scripts).
  • 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 might 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.
    • 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 is a commpkg upgrade sample session.

Upgrading to Calendar Server 6.3 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 HA Environment

The following instructions describe how to upgrade Calendar Server in an HA environment.

Note
To upgrade a Solaris x86 deployment, make sure that you are running at least Calendar Server 6.3 patch -20. See Upgrading to Calendar Server 6.3 Patch 12165820 or Later on Solaris x86 Platforms for more information.
  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
    local.hostname = "logical-host-name"
    local.servername = "logical-host-name"
  4. For each resource group non-online or non-active node
    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:

Silent Mode File Parameters
Parameter Description Example
VERB Indicates which function to perform.
You can add CLI arguments described in commpkg usage, however the —dry-run argument cannot be added to the install function in the state file.
VERB=install
ALTDISTROPATH Indicates an alternate distro path if —distro is not specified. ALTDISTROPATH=SunOS5.10_i86pc_DBG.OBJ/release
PKGOVERWRITE Overwrites the existing installation packages. PKGOVERWRITE=YES
INSTALLROOT Specifies installation root. INSTALLROOT=/opt/sun/comms
ALTROOT Specifies an alternate root. ALTROOT=yes
EXCLUDEOS Specifies to not upgrade operating system patches. EXCLUDEOS=YES
COMPONENTS Lists the components you want to install. 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 Indicates whether or not to accept license.
This property must be specified either in the state file or as a command line argument.
ACCEPTLICENSE=yes.
UPGRADESC Indicates whether all shared components should or should not be upgraded without prompting. 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

This information describes the data components and tools of message store, and how they affect data upgrades. It provides 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 yourself with this level of message store technical detail. However, if you need to customize your message store upgrade process, use this information as a guideline.

Topics:

Architecture and Components

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

Message Store and Components
This figure shows the Message Store and corresponding components.

The versions of Messaging Server and its message store are: 4.15, 5.x, 6.0, 6.1, 6.2, 6.3, 7.0, 7.1, 7.2, 7.3, 7.4, and 7.5. During this time, there have been four mailbox versions: 1_1, 1_2, 1_3, and 1_4.

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.

The 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 has complexities and implications for the data upgrade. (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.

Message Store Database Components

Messaging Server Mailbox Berkeley Database Database BTREE Database Log Files
4.15 1_1 2.6 6 2
5.x 1_2 2.6 6 2
6.0 1_2 3.2.9 8 3
6.1 1_2 4.2 9 8
6.2 1_2 4.2 9 8
6.3 1_2 4.4 9 11
7.0 1_3 4.4 9 11
7 Update 1 1_3 4.7.25 9 14
7 Update 2 1_3 4.7.25 9 14
7 Update 3 1_3 4.7.25 9 14
7 Update 4 1_3 4.7.25 9 14
7 Update 5 1_4 5.3.21 9 19

In general, 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. The following section describes the various compatibilities and incompatibilities.

Mailbox Version Compatibilities

The message store upgrades mailboxes from version 1_1 to 1_2, from 1_2 to 1_3, and from 1_3 to 1_4 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. The imcheck command opens every mailbox, which triggers the migration.

To upgrade from mail version 1_1 to 1_4, 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 the reconstruct -m and reconstruct -r commands.

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 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.x 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 64-bit so that you have enough virtual address space for the process.

Convergence requires webmail server 7.x. To use Convergence, you must upgrade mshttpd to 7.x.

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 (or from SPARC to x86), use imsbackup and imsrestore or rehostuser.

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.

The Messaging Server 6.2 stored -r command requires the watcher process. Make sure that the watcher is running before you perform stored -r.

The stored -r command was introduced in Messaging Server 6.1. Prior to Messaging Server 6.1, 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 8 Update 2 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 8 Update 2 in an HA Environment

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

To Upgrade to Instant Messaging Server 8 Update 2 Sun Cluster Agent (IM_SCHA)

Invoke the commpkg upgrade command on all nodes on the cluster. If cluster node is a non-global zone, invoke commpkg upgrade in global zone as well as in non-global zones.

Upgrading to Messaging Server 7 Update 3 in an HA (High Availability) Environment

Reviewers
This page has only been renamed for Communications Suite 7. Content has not been reviewed.

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:

Note
After configuring Messaging Server 7 Update 3 for HA or upgrading to Messaging Server 7 Update 3 in HA, if you are using a compiled configuration, you must recompile the configuration by issuing the command:
# imsimta cnbuild
Otherwise, the Messaging Server will fail to start in the HA environment.

Upgrading to Messaging Server 7 Update 3 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 Update 3 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 on the Messaging Server resource group online node.
      # msg_svr_base/sbin/ha_ip_config
      Note : This command is needed only if the current installed Messaging Server version is older then 7.0.
  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 msg_svr_base/config
  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 Communications Suite 6 or later), 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 Update 3 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 Messaging Server resource group online node.
    # msg_svr_base/sbin/ha_ip_config
    Note : This command is needed only if the current installed Messaging Server version is older then 7.0.
  4. Enable Messaging Server resource:
    # scswitch -e -j msg_svr_resource

Upgrading to the Messaging Server 7 Update 3 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 Update 3 Sun Cluster Agent (MS_SCHA)

  1. Run commpkg upgrade on all nodes on the cluster. Messaging Server should be upgraded to 7 Update 3 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 Update 3 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-version 7 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 Update 3 agent in the global zone.

To check if the older pre-version 7 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 Update 3 Sun Cluster Agent (MS_SCHA) in a Two-node Symmetric Sun Cluster HA Environment

  1. Upgrade Messaging Server to Version 7 Update 3 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 Update 3 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.

Copyright © 2012, 2013 Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

This product includes software developed by Computing Services at Carnegie Mellon University (http://www.cmu.edu/computing/).

Labels:
printable printable Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.