Tuesday, February 16, 2016

Email Migration Microsoft Exchange to Office 365 via imapsync

Yet another in the ever-expanding popular series of how to use imapsync (one of the best low-cost tools available) to migrate email to Exchange.  This time for Microsoft Exchange to Microsoft Exchange or Office 365.

Yes.  Microsoft offers tools for this, and we've documented them.

Evaluate them yourselves.  We have.  That's why we recommend imapsync. Full disclosure: we have no relationship with imapsync and derive exactly zero revenue from this non-existent relationship.

We see a wide spectrum of Exchange expertise (*cough* admin at university in Pennsylvania stymied by Junk E-mail folder *cough*) so we think it's useful to document this process.

Your comments are welcome and will be added and credited.

First step:
Make sure you are enabled for IMAP on both sides of your Exchange migration. 
We've gone over this in our post Quick guide to Enabling IMAP in @Office365 / #MSFTExchange 2013.

Second step:
Set up a Service Account with access to all your Exchange accounts. 
Confused about Exchange permissions and setting up your service account?  Read our post The Cookbook Version of Exchange 2013 Migration Rights.

Third step:
Test this before you do something rash.

Gilles (imapsync's AWESOMELY capable  author who deserves HUGE credit for his application) has a sensible method of beginning in his sample batch file (seen in this excerpt):

@REM Three other options are in this example because they are good to start with
@REM --dry makes imapsync doing nothing, just print what would be done without --dry.
@REM --justfolders does only things about folders (ignore messages). It is good
@REM               to verify the folder mapping is good for you.
@REM --automap guesses folders mapping, for folders like 
@REM           "Sent", "Junk", "Drafts", "All", "Archive", "Flagged".

Or: do a DRY run, make sure it's handling the folders you want, and let the application guess on your folder mapping (for Microsoft Exchange to Office 365 or Exchange not complex).

Not too controversial or inscrutable, right?

So for ONE USER where you have the password for that user on BOTH systems start with:

imapsync.exe ^

--host1 sumatra.com --user1 jimi.hendrix@sumatra.com --password1  "XXXX" ^
--host2 outlook.office365.com --user2 ^
jimi.hendrix@sumatra.onmicrosoft.com --password2 "XXXXX"  ^
--ssl2  --sep2 /  --dry --justfolders --automap

once things are doing what you want, you can turn this into:

imapsync.exe ^
--host1 sumatra.com --user1 jimi.hendrix@sumatra.com --password1  "XXXX" ^
--host2 outlook.office365.com --user2 ^
jimi.hendrix@sumatra.onmicrosoft.com --password2 "XXXXX"  ^
--ssl2  --sep2 /  --automap

If you set up a service account with FullAccess on Office 365, you accomplish a migration without knowing any password except your service account by using a command like this (where password2 is the service account password):

imapsync.exe ^
--host1 zimbra.sumatra.com  ^
--user1 jimi.hendrix@zimbra.sumatra.com --password1 "XXXX" ^
--host2 outlook.office365.com --port2 993 --sep2 / ^
--user2 jimi.hendrix@sumatra.onmicrosoft.com ^ 
--authuser2 SERVICE_ACCT@sumatra.onmicrosoft.com ^
--password2 "XXXXX"  --ssl2  --dry --justfolders --automap

remember --dry --justfolders are for debugging.

Note in  the above, for an Office 365 target system we need to use the "--sep2 /" command. 
Note also that this gives you the direct capability to map your user ID, for instance from "jimi.hendrix" on your legacy system to "jhendrix1967"  or "jimi.hendrix1967" on your target system.

Iterating over a user list
In any event you are going to need to generate a user list to migrate email.  Can you keep your migrating user list separate from your migration script?  Answer: YES. This method assumes your legacy ID is the same as your target ID, but allowing for this to change is not a hard extension.

The imapsync ZIP file contains a script for iterating on a user list:
Which also contains an excellent primer on running imapsync in parallel.
This batch file assumes a text file in the form "User1;Password1;User2;Password2;..."  (TIP: If you use a service account you will not need the password)

To get  a user list from Exchange get-mailbox is the simplest method :

get-mailbox | fl name,emailaddress   > myusers.txt

to give you full name, email address.
For just email address run:

get-mailbox | emailaddress   > myusers.txt

You could also use ldapsearch if you already have scripts for that.

If you want to get a list of all users in an OU to migrate by segments: 
get-mailbox (e.g., -organizationalunit users

More Migration Details

Throttling in Exchange/Office 365
You're more likely to be throttled in Office 365 since the controls to that environment are largely out of your hands.

As per our usual mantra: test everything before you go into production.

If you get throttled, there are two imapsync switches you can tweak.

One limits the transfer rate to a specific number of messages:

Start at 10 (say) and work up or down from there.  In calendar migrations we start with 25, but our gut experience tells us calendar data is smaller per object on average.

The other limits the transfer rate by byte if that works better for your network environment.

You can also check out our post Throttling in Exchange 2013.

Really helpful options
--buffersize 8192000  imapsync has a default I/O buffer of 4 Kb.  Upping this to 8 Mb will probably speed things for you
--syncinternaldates: Not for Exchange, but some email systems misuse email dates and you therefore run the risk of the receipt dates on your target system (what imapsync refers to as host2) becoming the date of insertion.  This command avoids that unfortunate event.
--fast:  this prevents flags from being synced and therefore makes the process (wait for it....) faster.  Not an option to invoke if you want / need to sync flags!
--dry:  this is a really useful option for development and debugging,  It just goes through the motions of logging onto both source and target system and displays the status -- a dry run.  Use this or debugging options -debug and -debugimap

See our section on Common Problems and Solutions in our Sumatra's DIY Guide to an Office 365 Migration.

No comments: