test

Sun Java System Messaging Server 6.3 Administration Guide

ProcedureTo Migrate User Mailboxes from One Messaging Server to Another While Online

Before You Begin

The requirements for this type of migration are as follows:

Note –

Some steps apply only if you are upgrading the messaging server from an earlier version to a later version. These steps might not apply if you are only migrating mailboxes from one message store to another. The steps that apply to migrating entire systems are noted.

  1. On the source system, split your user entries to be moved into equal backup groups using the backup-groups.conf file.

    This step is in preparation for the mailbox migration, Step 8, that occurs later in this procedure. See 20.12.2 To Create Backup Groups for detailed instructions.

    You can also place the user names into files and use the -u option in the imsbackup command.

  2. Notify users to be moved that they will not have access to their mailboxes until the move is completed.

    Ensure that users to be moved are logged out of their mail systems before the data move occurs. (See 20.13 Monitoring User Access.)

  3. Set the authentication cache timeout to 0 on the back-end message store and MMP systems, and ALIAS_ENTRY_CACHE_TIMEOUToption to 0 on the MTAs.

    1. On the back end message stores containing the mailboxes to be moved, set the authentication cache timeout to 0.


      configutil -o service.authcachettl -v 0

      This step and Step 7 (changing mailUserStatus to hold) immediately prevents users from accessing their mailboxes during migration.

    2. On all MMPs, set the LDAP and authentication cache timeout to 0.

      In ImapProxyAService.cfg and PopProxyAService.cfg set both LdapCacheTTLand AuthCacheTTL to 0.

    3. On any Messaging Server that hosts an MTA that inserts messages into mailboxes that are to be migrated, set the ALIAS_ENTRY_CACHE_TIMEOUT option to 0.

      Messaging Servers hosting an MTA that inserts messages into the migrating mailboxes will typically be the back end message store. However, if the system is using LMTP, then that system will be the inbound MTAs. Check your configuration to make sure.

      Resetting ALIAS_ENTRY_CACHE_TIMEOUT in /msg_svr_base/config/option.dat forces the MTA to bypass the cache and look directly at the LDAP entry so that intermediate channel queues (for example, the conversion or reprocess channels) see the new mailUserStatus (hold) of the users being moved rather then the out-of-date cached information. ALIAS_ENTRY_CACHE_TIMEOUT is in option.dat.

    4. Restart the systems on which the caches were reset.

      You must restart the system for these changes to take place. See 4.4 Starting and Stopping Services for instructions.

  4. Ensure that both your source Messaging Server and destination Messaging Server are up and running.

    The source Messaging Server must be able to route incoming messages to the new destination server.

  5. Change the LDAP attribute mailUserStatus on all user entries whose mailboxes will be moved from active to hold.

    Changing the attribute holds incoming messages in the hold queue and prevents access to the mailboxes over IMAP, POP, and HTTP. Typically, users will be moved in groups of users. If you are moving all the mailboxes of a single domain, you can use the mailDomainStatus attribute.

    For more information on mailUserStatus, see the mailUserStatus in Sun Java Communications Suite 5 Schema Reference.

  6. Make sure that messages addressed to mailboxes being migrated are not stuck in the ims-ms or tcp_lmtp* channel queues (if LMTP has been deployed).

    Use the following commands to see if messages exist in the channel queue directory tree and in the held state (to see .HELD files) addressed to a user to be migrated:


    imsimta qm directory -to=<user_address_to_be_migrated> -directory_tree

imsimta qm directory -to=<user_address_to_be_migrated> -held -directory_tree

    If there are messages in the queue, run these same commands later to see if the MTA has dequeued them. If there are messages that are not being dequeued, then you must address this problem before migrating. This should be a rare occurrence, but possible causes are recipient mailboxes being over quota, mailboxes being locked perhaps because users are logged in and moving messages, the LMTP backend server is not responding, network or name server problems, and so on).

  7. Change the LDAP attribute mailHost in the user entries to be moved as well as in any mail group entries*.

    Use the ldapmodify command to change the entries to the new mail server. Use the ldapmodify that comes with Messaging or Directory Server. Do NOT use the Solaris OS ldapmodify command.

    * You only need to change the mailHost attribute in the mail group entry if the old mail host is being shut down. You can either change this attribute to the new mail host name or just eliminate the attribute altogether. It is optional for mail groups to have a mailHost. Having a mailHost means that only that host can do the group expansion; omitting a mailHost (which is the more common case) means all MTAs can do the group expansion. Note that mail group entries do not have mailboxes to be migrated and typically do not even have the mailhost attribute.

    For more information on mailhost, see mailHost in Sun Java Communications Suite 5 Schema Reference.

  8. Move the mailbox data from the source Messaging Server message store to the destination Messaging Server message store and record the time when started.

    Back up the mailboxes with the imsbackup utility and restore them to the new Messaging Server with the imsrestore utility. For example, to migrate mailboxes from a Messaging Server 5.2 system called oldmail.siroe.com to newmail.siroe.com, run the following command on oldmail.siroe.com:


    /server-root/bin/msg/store/bin/imsbackup -f- /instance/group     \
| rsh newmail.siroe.com /opt/SUNWmsgsr/lib/msg/imsrestore.sh   \
-f- -c y -v 1

    You can run multiple concurrent backup and restore sessions (one per group) to maximize the transfer rate into the new message store. See the Command Descriptions in Sun Java System Messaging Server 6.3 Administration Reference for more information about the imsbackup and imsrestore utilities as well as 20.12 Backing Up and Restoring the Message Store.

    Note –

    When imsrestore or any processing intensive operation takes significantly more system resources than normal, and continues doing so longer than the msprobe interval, there may be a temporary backlog of DB transaction log files to be cleared. If there are more files than specified in local.store.maxlog, then msprobe may erroneously restart all the processes during a restore. To prevent this from happening, disable msprobe during the imsrestore.

    Note –

    Record the timestamp of when imsbackup is run for later delivery validation.

  9. (Conditional Step for System Upgrades) If your mailbox migration is part of the process of upgrading from an earlier version of Messaging Server to the current version, set this current version of Messaging Server to be the new default Messaging Server for the system.

    Change the DNS A record of oldmail.siroe.com to point to newmail.siroe.com (the server responsible for domain(s) previously hosted on oldmail.siroe.com).

  10. Enable user access to the new message store.

    Set the LDAP attribute mailUserStatus or mailDomainStatus, if applicable, to whatever value it had been before it was changed to hold (for example,active).

  11. Release the messages in the held state on all source Messaging Servers.

    Any system that may be holding incoming messages needs to run the following command to release all the user messages:


    imsimta qm release -channel=hold -scope

    where scope can be all, which releases all messages; user, which is the user ID; or domain which is the domain where the user resides.

  12. Reset the authentication cache timeout and the ALIAS_ENTRY_CACHE_TIMEOUT option to the default or desired values and restart the system.

    At this point, you've migrated all the user mailboxes that need to be migrated. Before proceeding, make sure that no new entries in LDAP have been created with the old system as the mailhost, and if some have, migrate them. Also, make sure that no such entries can be created by modifying the provisioning systems.

    You will also want to change the preferredmailhost attribute to the name of the new mail host.

    For back-end messages stores, set authentication cache timeout as follows:


    configutil -o service.authcachettl -v 900

    For the MMPs, in ImapProxyAService.cfg and PopProxyAService.cfg set the LdapCacheTTL and AuthCacheTTL options to 900.

    For MTAs, set the ALIAS_ENTRY_CACHE_TIMEOUT option to 600. ALIAS_ENTRY_CACHE_TIMEOUT is in option.dat.

    You must restart the system for these changes to take place. See 4.4 Starting and Stopping Services for instructions.

  13. Ensure that the user clients are pointing to the new mail server.

    After the upgrade finishes, have the users point to the new server through their mail client program (in this example, users would point to newmail.siroe.com from oldmail.siroe.com).

    An alternative is to use a messaging multiplexor (MMP) which obviates the need to have users point their clients directly to the new mail server. The MMP gets that information from the mailHost attribute which is stored in the LDAP user entries and automatically redirects the client to the new server.

  14. After everything works, verify that no messages were delivered to the old message store after the migration.

    Go to the old message store and run mboxutil -l to list the mailboxes. Check the last message delivery timestamp. If a message was delivered after the migration timestamp (the date stamp when you ran the imsbackup command), then migrate those messages with a backup and restore command. Because of the preparatory steps provided, it would be exceedingly rare to see a message delivered after migration.

    Theoretically, a message could be stuck in a queue for the number of days or hours specified by the notices channel keywords (see 10.10.4.3 To Set Notification Message Delivery Intervals).

  15. Remove duplicate messages on the new message store, run the relinker command.

    This command might free disk space on the new message store. See 20.11.7 Reducing Message Store Size Due to Duplicate Storage of Identical Messages.

  16. Remove the old messages from the store you migrated from and delete users from the database on the old store.

    Run the mboxutil -d command. (See 20.11.2.1 The mboxutil Utility).