Previous     Contents     Index     Next     
iPlanet Messaging Server 5.2 Installation Guide for UNIX



Appendix C   Upgrading Your Messaging Server


This appendix contains instructions to help you upgrade previous versions of iPlanet Messaging Server to iPlanet Messaging Server 5.2. It covers the following sections:



Pre-Upgrade Instructions

This section describes the steps you should follow prior to upgrading your iPlanet Messaging Server to version 5.2. The following topics are discussed:


Stop Messaging Processes

Prior to running the upgrade program, you should first stop specific messaging processes to ensure a successful upgrade. To do so, follow these steps:

  1. Stop accepting incoming mail by stopping the MTA dispatcher with the imsimta stop dispatcher command. For more information on MTA commands, see the iPlanet Messaging Server Reference Manual.

  2. Stop the rest of the services that can be used to modify Messaging Server settings. Specifically, stop the following services with the appropriate commands:

    • msgserver-root/stop-admin

    • msgserver-root/msg-instance/stop-msg

    • webserver-root/https-admserv/stop

    • webserver-root/https-machine/stop
      Note Do not stop the Directory Server; it should be running when you upgrade the messaging server.


  3. If you have installed High Availability, go to the section Upgrade to Messaging Server 5.2 with High Availability. If you have not installed High Availability, go directly to the next section (Back Up the Existing Messaging Server Installation).


Back Up the Existing Messaging Server Installation

Prior to beginning the upgrade process, it is strongly recommended that you back up your messaging server installation. To do so, follow these steps:

  1. It is recommended that you back up the entire server-root directory by using a backup mechanism you already have in place.

  2. Determine if there are messages in the message queues (directory msgserver-root/msg-instance/imta/queue). These queues contain messages that were in transit when the servers were stopped as described in the section on Stop Messaging Processes.

    If the message queues contain any messages, be sure to save the msgserver-root/msg-instance/imta/queue directory in a different location.

  3. To perform a full backup of the LDAP Directory Server, run the db2ldif program in directory server-root/slapd-instance/ for each slapd instance (in particular, the configuration and the users/groups directories). The db2ldif file will export the data to an LDIF file using a date.ldif file naming convention in the msgserver-root/slapd-instance/ldif directory.

  4. While a full backup of the LDAP directory server is recommended, you might want to only perform selective backups. With the ldapsearch command, you can selectively back up the users/groups or personal address book entries. The following examples assume that the users/groups suffix is siroe.com and the users/group directory administrator is cn=Directory Manager. In the first example, entries with a suffix of o=siroe.com are retrieved and saved in the LDIF file /var/tmp/date.ug.ldif:
    ldapsearch -L -h ldapserver -D "cn=Directory Manager" \
    -w     passwd -b "o=siroe.com" "objectclass=inetlocalmailrecipient" \
    > /var/tmp/    date.ug.ldif

    In the second example, entries with a suffix of o=pab are retrieved and saved in the LDIF file /var/tmp/date.pab.ldif:
    ldapsearch -L -h ldapserver -D "cn=Directory Manager" \
    -w     passwd -b "o=pab" "objectclass=*" \
    > /var/tmp/    date.pab.ldif

    For more information on the ldapsearch command, refer to the iPlanet Directory Server documentation.

  5. Save the Message Store by renaming the following directory where the message store is stored:

    msgserver-root/msg-instance/store/partition/primary

    and create an empty directory in its place.

    If you mounted the entire Message Store in your installation, you can unmount the store to ensure that it is not written to during the upgrade. Use the following command:

    umount msgserver-root/msg-instance/store/partition/primary

  6. Save the existing files in the server-root directory by copying them to another directory location (You can exclude the message store, since you have already saved it in Step 5.). Saving the existing files in the server-root directory can recover the Messaging Server configuration if the upgrade fails for any reason.


Upgrade Directory Server

If the Messaging Server version to which you are upgrading uses the same Directory Server version as your existing Directory Server, you do not need to upgrade the Directory Server. However, if your existing directory server is, for example, Netscape Directory Server 4.13, you will need to upgrade the Directory Server, since iPlanet Messaging Server 5.2 is bundled with Netscape Directory Server 4.16.

Be sure you are logged in as root when you upgrade the Directory Server. To upgrade the Directory Server, follow these steps:

  1. Run the Messaging Server program from the product binaries and install Directory Server in the same server-root directory as the previous instance of Directory Server. For example,

    # /usr/iplanet/server5/slapd-budgie/setup -k

  2. When you are asked about the iPlanet Server Products Components you want to install, select Components 1 (Netscape Server Products Core Components), 2 (Netscape Directory Suite), and 3 (Administration Services). Do not to select Component 4 (Messaging Server Components) if you are upgrading only the directory server.
    Note You will need to run the setup program for each directory server instance.


  3. Save the generated install.inf (located in dirserver-root/setup/install.inf) file that you created by using the -k option with the setup command.

  4. Run the ims_dssetup.pl script to prepare your directory server for the Messaging Server upgrade. For more information, see Running the ims_dssetup Utility.



Upgrade to Messaging Server 5.2

To upgrade from an older version of iPlanet Messaging Server (such as iPlanet Messaging Server 5.1), follow these steps:

  1. During initial installation, the following files and directories are backed up:

    server-root/msg-instance/config/local.conf
    server-root/msg-instance/config/msg.conf
    server-root/msg-instance/imta/config
    server-root/msg-instance/html

    These configuration directories and files are moved to the server-root/msg-instance/backup.timestamp directory where timestamp indicates the time at which the installation took place.

  2. After the upgrade, you should compare these backed-up configuration files to the new configuration files in the server-root/msg-instance/imta/config/ and reapply any customized settings.
    Note To facilitate the upgrade process, it is recommended that you review the parameters you recorded in Table 1-2.


  3. Make sure that your upgrade takes place on the same machine and the same server-root where you originally installed iPlanet Messaging Server.

  4. Login as root and run ./setup -k from Messaging installation binaries. This is the same setup program you would run if you were installing a new instance of Messaging Server.

  5. When you are asked about the iPlanet Server Products Components you want to install, select Components 1 (Netscape Server Products Core Components), 3 (Administration Services), and 4 (Messaging Server Components) if you have already upgraded your directory server. If you did not upgrade your directory server, select the default (Components 1, 2, 3 (Directory Server Components), and 4).

  6. During the installation process, Installer detects existing file, directory, and configuration values as the defaults and fills in missing values with standard default suggestions. You will get the following question when Installer detects the existing configuration values of your prior Messaging Server installation:

    This machine has a Messaging Server instance installed already. Please choose below whether you want to upgrade the existing server instance or create a new server instance.

    If you choose to create a new server instance, the configuration for the existing server instance will not be touched. If you choose to upgrade the existing server instance, any missing configuration will be detected and the configuration will be repaired if necessary.

       [1] Create New
       [2]  Upgrade

    Choose option 2 to upgrade your Messaging Server.

  7. When you are asked about the LDAP URL of the Directory Server, be sure to specify the URL of the LDAP configuration Directory Server.

  8. If the service administrator ID you chose during the original installation was not the ServiceAdmin default, you will be asked to re-enter your service administrator ID and password from the original installation.

The upgrade process will complete once Installer updates the necessary configuration values.
Note Mailbox and message queues do not require migration from a 5.x to 5.2 system.


Note that after you have completed upgrading Messaging Server, the server processes will not start by default. Instead, you will need to manually start these processes. For more information on the STORED, POP, IMAP, HTTP, and MTA processes, see chapter on configuring general messaging capabilities in the iPlanet Messaging Server Administrator's Guide.


Post-Upgrade Instructions

After completing the Messaging Server upgrade, follow these additional steps:

  1. To keep the result of the upgrade, save the following configuration files in another location:

    msgserver-root/setup/install.inf
    msgserver-root/msg-instance/config/local.conf
    msgserver-root/msg-instance/config/msg.conf
    msgserver-root/admin-serv/config/adm.conf
    msgserver-root/setup/msg/*.log

  2. If you unmounted user mailboxes, you can now remount them. Or, if you moved the Message Store directory, you can now move the directory back to its original location (msgserver-root/msg-instance/store/partition/primary).

  3. Run the ims_dssetup.pl script to enable the MTA direct LDAP lookup feature. For more information, see Running the ims_dssetup Utility. For more information on the MTA direct LDAP lookup feature, see the iPlanet Messaging Server Administrator's Guide.

    If you already ran the ims_dssetup.pl script in Step 4 of Upgrade Directory Server, you should skip this step.

  4. If you have an existing iPlanet Web Server, you should upgrade it to the version supported (iPlanet Web Server 6.0 Service Pack 2) with iPlanet Messaging Server 5.2. While you cannot upgrade from previous versions of iPlanet Web Server or Netscape Enterprise Server to iPlanet Web Server 6.0 SP2, you can migrate your 4.x web server. For more information, refer to the iPlanet Web Server Installation and Migration Guide.

  5. If you have an existing iPlanet Delegated Administrator for Messaging and Collaboration to manage users and groups, you will need to uninstall that version and install the version supported (iPlanet Delegated Administrator for Messaging and Collaboration 1.2) with Messaging Server 5.2.

    During the Delegated Administrator uninstall process, the web server configuration files, containing the Delegated Administrator-related data, are backed up and renamed with .nda extensions (for example, servlets.properties.nda). Consequently, you can keep the configuration from your previous version of Delegated Administrator. For more information, see the iPlanet Delegated Administrator for Messaging and Collaboration Installation and Administration Guide.

  6. Restart the Messaging Server processes (Note that the Administration Server will automatically be started once the upgrade is finished):

    # msgserver-root/msg-instance/start-msg

    Use the following command if you are in a High Availability environment:
    # msgserver-root/msg-instance/start-msg ha

  7. After restarting the Messaging Server processes, check for any errors by reviewing the mail.log_current file in directory msgserver-root/msg-instance/log/imta.

    Additionally, you should monitor the message queues to ensure that messages are not stuck in any queue.



Upgrade to Messaging Server 5.2 with High Availability

This section will explain how to upgrade Messaging Server with Sun Cluster or Veritas Cluster Servers. The following sections are described:


To Upgrade to Messaging Server 5.2 with Sun Cluster 2.2

If you want to upgrade to iPlanet Messaging Server 5.2 and you have installed Sun Cluster 2.2 with a previous version of iPlanet Messaging Server, you should be sure to start the upgrade on the physical host that is currently mastered by the logical host. In addition, you should follow these steps:

  1. Run the hareg -n command to shut down the Sun Cluster service.

  2. Run the hareg -u iMS50 command.

  3. If the directory server is installed in the same server-root directory as messaging server, be sure the directory server is running.

  4. Back up the existing Messaging Server. Review the instructions in Back Up the Existing Messaging Server Installation.

  5. Upgrade the Directory Server, if necessary. Review the instructions in Upgrade Directory Server.

  6. Upgrade the messaging server. See Upgrade to Messaging Server 5.2 for more information.

  7. Configure Sun Cluster 2.2 by following the instructions in Sun Cluster 2.2 Agent Installation.
    Note It is strongly encouraged that you use Sun Cluster 3.x, since Sun Cluster 2.2 is a deprecated product as of this release. For more information, see the iPlanet Messaging Server 5.2 Release Notes.



To Upgrade to Messaging Server 5.2 with Veritas Cluster Server

If you want to upgrade to iPlanet Messaging Server 5.2 and you have installed Veritas Cluster Server with a previous version of iPlanet Messaging Server, you should follow these steps to upgrade:

  1. Bring the iMS5 service group offline and disable its resources.

  2. Remove the dependencies between the mail resource, the logical_IP resource, and the mountshared resource.

  3. Bring the iMS5 service group back online.

  4. If the directory server is installed in the same server-root directory as messaging server, be sure the directory server is running.

  5. Back up the existing Messaging Server. Review the instructions in Back Up the Existing Messaging Server Installation.

  6. Upgrade the Directory Server, if necessary. Review the instructions in Upgrade Directory Server.

  7. Upgrade the messaging server. See Upgrade to Messaging Server 5.2 for more information.

  8. Start the dependency tree as outlined in Step 6 of the Veritas Cluster Server Pre-Installation Instructions and follow the rest of the Veritas Cluster Server installation instructions described in Chapter 4 "High Availability."


To Upgrade to Messaging Server 5.2 with Sun Cluster 3.x

If you want to upgrade to iPlanet Messaging Server 5.2 and you have installed Sun Cluster 3.0, Sun Cluster 3.0 Update 1, or Sun Cluster 3.0 Update 2 with a previous version of iPlanet Messaging Server, you should first upgrade the Messaging Server installation. See Upgrade to Messaging Server 5.2.

After completing the Messaging Server installation, you need to install the SUNWscims package (from the Messaging Server 5.2 CDROM) on each cluster node. See Sun Cluster 3.0 U1 and U2 Agent Installation for more information. This process will upgrade your Messaging Server HA Agent.



Backout Procedure


If at any time you need to back out of the upgrade process, you should follow these steps to ensure a successful backout:
Note The backout procedure assumes that you have done a full backup of your Messaging Server. For more information, see Back Up the Existing Messaging Server Installation.


  1. Stop iPlanet Delegated Administrator for Messaging and Collaboration (if installed), iPlanet Web Server (if installed), Messaging Server, Directory Server, and Administration Server processes.

    Be sure to stop the processes in the order indicated above.

  2. Unmount the Message Store directory:

    umount msgserver-root/msg-instance/store/partition/primary

    If you did not back up your Message Store directory, you can save the directory in another location.

  3. Restore the Messaging Server from the backup. See Back Up the Existing Messaging Server Installation for more information.

  4. Remount the user mailboxes with the following command:

    mount msgserver-root/msg-instance/store/partition/primary

    Or, you can move the directory back to the msgserver-root/msg-instance/store/partition/primary from the location where you initially saved it. See Step 2.

  5. Start the Administration Server, Directory Server, Messaging Server, iPlanet Web Server (if installed), iPlanet Delegated Administrator for Messaging and Collaboration (if installed) processes.

    Be sure to start the processes in the order indicated above.


Previous     Contents     Index     Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated February 26, 2002