How does move mailbox really work?

Evan Dodds has posted this high level desription of how mailboxes are actually moved.

Move mailbox is the best, supported way to move mailbox data between Exchange servers and update the directory object. It’s been around for ages and has been improved with each version. In Exchange 2003, for instance, the mailbox moves can now be scheduled and are multi-threaded to dramatically improve performance. Exchange 2003 SP1 added the ability to move mailboxes cross-site while still in mixed mode.

There are a number of resources on how to do move mailbox between Exchange servers (KB.224975 and KB.328810 are two good examples), but what’s missing is a good high-level description of what goes on behind the scenes to make it all happen. This post focuses on Exchange 2003, but much of this applies to earlier versions as well. There’s a bunch of additional steps required for cross-site moves, but those are covered in other places.

After you click the last “Next” in the move mailbox wizard what happens?

All of the data provided to the wizard is processed and the move actually begins. There are a number of distinct steps we’ll talk about that are part of the mailbox move.

1) Wait for the scheduled time to arrive

Exchange 2003 provides a new function that allows you to schedule the time/date of the mailbox move. If you use this new feature, a second GUI window is opened up automatically to keep running until the scheduled time arrives and then perform the moves. This means that you don’t have to leave the original GUI window open after the scheduled move is set.

In any event, eventually the time of the move will be reached – either right away in the same GUI window or at some later point in the secondary GUI window – and the move will begin.

2) MAPI connection is opened to the source and destination servers

It’s important to understand that MAPI is used to facilitate the actual move. All Exchange servers have a basic server version of MAPI installed which is sufficient for the sort of MAPI operations that are required of the server, but note that this is a very different version of MAPI than is included with Outlook (it is because of conflicts between these two MAPI implementations that installing Outlook on an Exchange server is not a supported scenario).

The dependence on MAPI to move the data means that the requirements for MAPI connections must also be met for mailbox moves. For instance, an RPC connection must be made from the workstation or server running the move GUI to both the source server and to the server which is the destination of the move. If network ports are blocked between these systems, the MAPI connection won’t work. Similarly, if there is high latency or poor bandwidth availability in the network connections between these systems, this will also lead to poor mailbox move performance or failed moves.

3) Set PR_IN_TRANSIT flag in source mailbox

This is a flag stored in the source mailbox before the move begins to indicate to the source store that the mailbox is in the process of being moved. If this flag is set on a mailbox, this prevents the store from allowing new mail being delivered to the mailbox or other changes from being made to the mailbox during the move. It’s because of this flag that there’s no need to disallow logons to the mailbox while the mailbox is “in transit”.

4) Create the target mailbox

The mailbox is created in the target store and some of the basic mailbox properties and folders are set prior to moving the actual data. PR_IN_TRANSIT is also set on the target mailbox so that no mail delivery or logons will happen during the move.

5) Attempt to move the mailbox

For performance reasons, the mailbox move is attempted using a fast method that attempts to move the mailbox as a single object rather than moving each message individually. This move is done by calling the MAPI function IMapiProp::CopyTo() on the mailbox object. If the number of “bad items” selected within the wizard – this defaults to three – is exceeded during the move, the mailbox move fails and the progress is rolled back.

6) If the mailbox data is moved successfully, update the directory object

Once the mailbox data is all moved to the target store, the directory entry (or directory entries if 5.5 is involved in the move) need to be updated to reflect the new mailbox location. The AD attributes are: HomeMDB, HomeMTA, and msExchHomeServerName. The 5.5 attributes are: HomeMDB and HomeMTA.

The 5.5 directory updated by this process is that of the source server. If the source server doesn’t have a 5.5 directory, this step is skipped. If the target of the move is a 5.5 server, the move mailbox process also updates the HomeMDB and HomeMTA attributes directly at the target server in case the user logs into their mailbox before directory replication can happen.

If a mailbox is moved from an Exchange 2003 server to a server running an earlier version of Exchange (5.5 or 2000), the “wireless” attributes are also stripped off at this stage. These AD attributes are: msExchOmaAdminWirelessEnable and msExchOmaAdminExtendedSettings.

If these directory updates fail, the mailbox move is rolled back. If they succeed, then the mailbox move is done and it’s considered a successful move!

7) Clean up after a successful move!

If it’s been a successful move, we’ll have made a copy of all of the mailbox data from the source to the destination store. We won’t yet have done anything to the data in the source mailbox store (just in case the move had failed, we’d need to be able to roll back easily).

After the move is deemed successful, the mailbox in the destination store is updated to ensure the PR_IN_TRANSIT flag is no longer set. This will allow the user to login to the moved mailbox and will allow new mail (including any mail that queued up diring the move) to be delivered.

The mailbox in the source store is then removed and control is returned to the wizard so that the XML report of the mailbox move can be saved and reviewed!

Are there any myths about mailbox move I should know about?

A very common misconception is that the user must be logged off their mailbox while it is moved. This is not true, since as soon as the mailbox move is begun the PR_IN_TRANSIT flag is set on the mailbox which prevents further actions from occurring within the mailbox, protecting it during the move. There are a number of registry settings some folks have used to disable logons during mailbox moves, and while preventing logons during the mailbox moves won’t hurt anything, they’re simply not necessary.

Another myth is that the MTA must be running during an Exchange 2003 mailbox move. While this was the case in Exchange 5.5 and 2000, it is NOT the case in Exchange 2003. The MTA was required during mailbox moves in earlier versions of Exchange because when the PR_IN_TRANSIT is released on the target mailbox (in step #7, above), any mail that had been queued up for the moved mailbox would be dropped into the MTA for rerouting into the (now moved) mailbox destination. In Exchange 2003, this function is no longer reliant on the MTA routing and therefore the MTA is no longer involved in mailbox moves in this manner.

What happens to mail during the mailbox move?

During the time the mailbox is being moved, we’ve set this PR_IN_TRANSIT flag on the mailbox (on both the source and the destination mailbox). This tells the store that it cannot take local delivery of any mail into the mailbox that is being moved.

As mentioned above, in earlier versions of Exchange, during the mailbox move, mail is delivered into a special folder in the mailbox store as a temporary holding place until the mail can be delivered to the proper mailbox. Once the mailbox move is done, this mail is released to the MTA for rerouting into the destination store. However, in Exchange 2003 this is no longer the case.

In Exchange 2003, when mail fails to deliver due to the mailbox being marked “ecMailboxInTransit”, the mail is dropped into the “Messages queued for Deferred Delivery” queue within SMTP. After the mailbox move is completed and PR_IN_TRANSIT is released, the mail is rerouted through Store Driver and SMTP advanced queuing so that it is directed to the appropriate destination mailbox. This all happens transparently in the background.

What about stopping the ADC during mailbox move?

In a mixed-mode Exchange environment, the ADC can interfere with intra-site mailbox moves. If the ADC is running and a conflicting change is made to the directory object, the HomeMDB attribute can be reset to the source server. If this happens, the mailbox will appear to be “split” between the source and the destination server. To avoid this situation, be sure to stop the ADC when moving mailboxes between servers in the same site (see KB.299473 for more info). Also, be sure you don’t make any changes to mailbox objects using the 5.5 Administrator GUI while you’re moving mailboxes from the Exchange System Manager on Exchange 2000/2003!

Note that this behavior does NOT affect mailbox moves cross-site. ADC does not need to be stopped while moving mailboxes between sites using the Exchange 2003 SP1 feature.