Upgrading the Message Store

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

This document includes the following topics:

Architecture and Components

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

Full Size

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

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

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

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

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

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

Message Store Component Version Compatibilities

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

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

Mailbox Version Compatibilities

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

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

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

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

Upgrading and Downgrading the Berkeley Database (BDB)

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

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

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

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

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

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

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

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

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

Database Btree File

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

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

Database Log Files

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

The following message is logged when the server restart.

'Skipping log file...historic log version'

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

IMAPD, MSHTTPD and Sun Convergence

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

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

Upgrading From Messaging Server 32-bit to 64-bit

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

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

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

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

Migrating from x86 to SPARC

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

stored -r

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

For example:

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

Make sure stored -r completes successfully.

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

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

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

ims_db_upgrade

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

Downgrading

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