66 Migrating Mailboxes to a New System

Oracle Communications Messaging Server provides several ways to move or relocate mailboxes from one Messaging Server host (mailhost) to another.


For More Information:

Tools Summary for Relocating Messaging Server Users to a New Mailhost

The following tools are available for relocating users from one mailhost to another:

  • rehostuser, Enables you to move a Messaging Server user's mail store from one mailhost to another. The rehostuser utility also disconnects any active session, locks the store to ensure atomicity of the move from the user's perspective (no loss of data, flag change, and so on), changes the user's LDAP entry, flushes LDAP caches as necessary, and causes any queued mail to be rerouted to the new store. See "rehostuser" for more information.

  • imsbackup | imsrestore: Manually backs up the account from one host and restores on another. Can be combined with ssh and "piped" across the network. You can also back up to a file and then access that file from the other host through NFS, or move the file in between.

  • imsimport: Imports messages from a UNIX /var/mail format file into the Messaging Server message store.


  • If both the source and destination mailhosts are installed with at least Messaging Server 7, use "rehostuser." The rehostuser utility solves issues present in the other solutions, such as preventing users from accessing mail while it is being moved, making sure mail is held in the MTA during the move and redirected to the new message store, and so on.

  • You can manually run "imsbackup" on one host and "imsrestore" on the other host. You can combine multiple users in one step. You can combine "imsbackup" with ssh or NFS, or you could use gzip and transfer the backup file from one host to the other by using ftp. This method is actually used within the rehostuser utility. However, rehostuser shields you from having to set the users' status, disconnect them, and so on. If you use imsbackup and imsrestore manually, you also need to deal with those details manually. But if you have a large amount of data to move and can afford for the MTA and IMAP user access to be down while it is being moved, this method might be more efficient.

  • Similar to imsrestore and imsbackup, you can use "imsimport" to import UNIX /var/mail format files into the message store. If you are moving from a non-Oracle server and it does not have IMAP access capability, perhaps you can get it to export the folders in UNIX /var/mail format and then import them this way.

Migrating Mailboxes from an x86 Host to a SPARC Host

The message store data formats are architecture dependent. You cannot transfer any data components in "Message Store Component Version Compatibilities" from one architecture to another directly. To migrate the message store from an x86 host to a SPARC host (or from a SPARC host to an x86 host), use imsbackup and imsrestore, or rehostuser.

Moving Mailboxes to Another Messaging Server While Online

You can migrate the message store from an older version of Messaging Server to a newer version, or move mailboxes from one Messaging Server message store to another, while remaining online. This procedure works for iPlanet Messaging Server 5.0 and later. You cannot move messages from prior versions of Messaging Server or a non-Oracle Communications Suite message store. Moving mailboxes while online have the following advantages and disadvantages.


  • You can move the mailboxes from the old source system to the new destination system without user involvement.

  • This process is faster than any of the other processes.

  • Re-linking is not required if you are moving an entire partition.

  • Both Messaging Server systems remain active and online.

  • You can migrate all the mailboxes on a messages store or a subset of those messages. This procedure allows for incremental migrations.


  • This method does not work with non-Oracle Communications Suite messaging servers.

  • The users being migrated do not have access to their mailboxes until the migration of their own mailbox is complete.

  • This method can be complex and time consuming.

Incremental Mailbox Migration While Online

Incremental migration provides numerous advantages for safely and effectively moving your message store to a different system or upgrading to a new system, incremental migration allows you to build a new back-end message store system alongside the old back-end message store. You can then test the new system, migrate a few friendly users, then test the new system again. Once you are comfortable with the new system and configuration, and you are comfortable with the migration procedure, you can start migrating real commercial users. These users can be split into discrete backup groups so that during migration, only members of this group are offline, and only for a short time.

Another advantage of on-line incremental migration is that you do not have to plan for a system-wide back out in case your upgrade fails. A back out is a procedure for reverting changes you have made to a system to return the system to the original working state. When doing a migration, you have to plan for failure, which means that for every step in the migration requires a plan to return your system back to its previous operational state.

The problem with offline migrations is that you can't be sure your migration is successful until you've completed all the migration steps and switched the service back on. If the system doesn't work and cannot be quickly fixed, you'll need a back out procedure for all the steps performed. This can be stressful and take some time, during which your users will remain offline.

With an online incremental migration you perform the following basic steps:

  1. Build the new system alongside the old one so that both can operate independently.

  2. Configure the old system for coexistence with the new.

  3. Migrate a group of "friendly" users and test the new system and its coexistence with the old system.

  4. Divide the users on the old system into groups and migrate group by group to the new one as desired.

  5. Disassemble the old system.

Because both systems will coexist, you have time to test and get comfortable with the new system before migrating to it. If you do have to perform a back-out procedure, which should be very unlikely, you only have to plan for steps 2 and 4. Step 2 is easy to revert because you do not ever touch user's data. In step 4, the backout is to revert the user's state to active and their mailhost attribute back to the old host. No system-wide back out is required.

Online Migration Overview

Migrating mailboxes while remaining online is a straightforward process. Complications arise when you try to ensure that messages in transit to the mailbox (sitting in an MTA channel queue waiting for delivery) are not lost in the migration process. One solution is to hold messages sent during the migration process in a held state and wait for the messages in the various channel queues to be delivered. However, messages can get stuck in queues because of system problems or because a particular user is over quota. In this case, you must address this situation before migrating the mailboxes.

You can take various measures to reduce the likelihood of lost messages and to verify that messages are not stuck in a channel queue, but at a cost of increased complexity of the procedure.

The order and necessity of steps in the procedure vary depending upon your deployment and whether every message addressed to every mailbox must not be lost. This section describes the theory and concepts behind the steps. It is incumbent on you to understand each step and decide which to take and in which order, given your specific deployment. Following is an overview of the process of moving mailboxes. This process might vary depending upon your deployment.

  1. Block user access to the mailboxes being moved.

  2. Temporarily hold messages addressed to the mailbox being moved.

  3. Verify that messages are not stuck in the channel queues.

  4. Change the user's mailhost attribute to the new mailbox location.

  5. Move the mailboxes to the new location.

  6. Release held mail to be delivered to the new mailbox and enable incoming messages to be delivered to the migrated mailboxes.

  7. Examine the old message store to see if any messages were delivered after the migration.

  8. Unblock user access to mailbox.

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

The requirements for this type of migration are as follows:

  • stored should be running on both the source (old) and destination (new) messaging servers.

  • The source system and destination system must be able to route messages to each other if both systems will operate in co-existence. This is needed, for instance, so that delivery status notification messages can be generated on the destination system and get delivered to the source system.


    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 by using the backup-groups.conf file. This step is in preparation for the mailbox migration, Step 8, that occurs later in this procedure. See "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 "Monitoring User Access to the Message Store.")

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

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

      msconfig set base.authcachettl -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. For the IMAP proxy and POP proxy, set both ldapcachettl and authcachettl to 0. For example:

      msconfig> set imapproxy.authcachettl 0
      msconfig# set imapproxy.ldapcachettl 0
      msconfig# set popproxy.authcachettl 0
      msconfig# set popproxy.ldapcachettl 0
      msconfig# write
    3. On any Messaging Server host that contains an MTA that inserts messages into mailboxes that are to be migrated, set the alias_entry_cache_timeout option to 0. Messaging Server hosts that run an MTA that inserts messages into the migrating mailboxes are typically the back-end message store. However, if the system is using LMTP, then that system is the inbound MTA. Check your configuration to make sure. Resetting the alias_entry_cache_timeout option 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.

    4. Restart the systems on which the caches were reset. You must restart the system for these changes to take place. See "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 are 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 attribute in the 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 no use the Oracle Solaris 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. 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 the mailHost attribute in the 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 system called oldmail.example.com to newmail.example.com, run the following command on oldmail.example.com:

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

    You can run multiple concurrent "imsbackup" and "imsrestore" sessions (one per group) to maximize the transfer rate into the new message store. See also "Backing Up and Restoring the Message Store."


    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 store.maxlog, then msprobe may erroneously restart all the processes during a restore. To prevent this from happening, disable msprobe during the imsrestore.


    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.example.com to point to newmail.example.com (the server responsible for domain(s) previously hosted on oldmail.example.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 also want to change the preferredmailhost attribute to the name of the new mail host. For back-end messages stores, set authentication cache timeout to 900 as follows:

    msconfig set base.authcachettl 900

    For the IMAP proxy and POP proxy, set both ldapcachettl and authcachettl to 900. For example:

    msconfig> set imapproxy.authcachettl 900
    msconfig# set imapproxy.ldapcachettl 900
    msconfig# set popproxy.authcachettl 900
    msconfig# set popproxy.ldapcachettl 900
    msconfig# write

    For MTAs, set the alias_entry_cache_timeout option to 600.

    msconfig set mta.alias_entry_cache_timeout 600

    You must restart the system for these changes to take place. See "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.example.com from oldmail.example.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 that 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 options. See the discussion on setting notification message delivery intervals in the Messaging Server Reference).

  15. Remove duplicate messages on the new message store, run the relinker command. This command might free disk space on the new message store.

  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 "mboxutil.")

To Move Mailboxes Using an IMAP Client

This procedure can be used anytime messages need to be migrated from one messaging server to a different messaging server. Consider the advantages and disadvantages before moving mailboxes using this method.


  • This method can be used to migrate from a non-Oracle Communications host to the Messaging Server host. It can also be used to move mailboxes from one physical server to a different physical server.

  • After you set up the new mail server or message store, responsibility for moving mailboxes to the new system is left to users.

  • The process for moving mailboxes is relatively simple.

  • User access to mailboxes does not have to be disabled.


  • Requires that both the old and new systems be simultaneously running and accessible to users.

  • Cumulatively, this method takes longer to move mailboxes than other methods.

  • Responsibility for moving mailboxes to the new system is left to users.

  • The size of the new message store will be significantly larger than the old message store until the re-linking operation is performed.

  1. Install and configure the new Messaging Server.

  2. Set store.relinker.enable to 1. This reduces the message store size on the new system caused by duplicate storage of identical messages.

  3. Provision users on the new Messaging Server. You can use Delegated Administrator to do this. As soon as users are provisioned on the new system, newly arriving mail is delivered to the new INBOX.

  4. Have users configure their mail client to view both new and old Messaging Server mailboxes. This may involve setting up a new email account on the client. See mail client documentation for details.

  5. Instruct users to drag folders from their old Messaging Server to their new Messaging Server.

  6. Verify with users that all mailboxes are migrated to the new system, then shut down the user account on the old system.

To Move Mailboxes by Using the imsimport Command

This procedure is specifically used to move mailboxes from UNIX /var/mail format folders into a Messaging Server message store. However, if the Messaging Server host from which you are migrating can convert the IMAP message stores to UNIX /var/mail format, then you can use the imsimport command to migrate messages to Messaging Server. Consider the advantages and disadvantages before moving mailboxes using this method.


  • You have complete responsibility for moving mailboxes from the old system to the new system. Users do not have to do anything.


  • This method takes longer to move mailboxes than the other non-IMAP methods.

  • Users access to mailboxes must be disabled while mailboxes are being moved.

  • The size of the new message store will be significantly larger than the old message store until the re-linking operation is performed.

  1. Install and configure the new Messaging Server.

  2. Set store.relinker.enabled to 1. This reduces the message store size on the new system caused by duplicate storage of identical messages.

  3. Provision users on the new Messaging Server if needed. You can use Delegated Administrator to do this. Do not switch over to the new system yet.

  4. Disable user access to both the new and old messaging store. Set the mailUserStatus LDAP attribute to hold. User's mail is sent to the hold queue and access to the mailbox over IMAP, POP, and HTTP is disallowed. MTA and Message Access Servers on the store server must comply with this requirement. This setting overrides any other mailDeliveryOption settings.

  5. If the mail store from the existing mail server is not already in the /var/mail format, convert the mail store to /var/mail files. Refer to the third-party mail server documentation.

  6. Run the imsimport command. For example:

    imsimport -s /var/mail/joe -d INBOX -u joe

    See the "imsimport" for details.

  7. Enable user access to the message store. Set the mailUserStatus LDAP attribute to active.

  8. Enable user access to the new messaging store.

  9. Shut down the old system.