The ExMerge UI provides an interface to the options most relevant to a typical import/export operation. Getting away from the comfort of buttons, list controls et al, the command-line interface awaits us bringing better control and greater flexibility.

The command-line is the right environment for running unattended processes on a scheduled basis, or for the inclusion in any type of batch process. This is ideal to organizations using ExMerge to perform regular brick level backups.

Apart from increased flexibility, batch mode operation provides access to additional configuration options that the wizard interface does not expose. For example the UI only allows selecting mailboxes from one Exchange server. In batch mode, the ability to specify mailbox distinguished names overcomes this limitation.

In reality ExMerge supports a fairly limited set of command-line options. Most settings are configurable through an external INI file. Storing settings in an external file is quite advantageous. It allows us to start from an INI configured with the most typical settings. Thereafter individual ExMerge runs only require tweaking those values requiring customization.

The easiest way to generate the initial INI file is to run the ExMerge wizard, whose last step provides a 'Save Settings' button. This saves all the configured settings to exmerge.ini, ready for reuse.

To start batch mode, the minimal ExMerge command-line is:
exmerge.exe -B

This causes ExMerge to silently load settings from exmerge.ini and perform the configured operation. A report on the process outcome is saved at exmerge.log.

Other supported command-line switches include:
-F for specifying the full path to the configuration INI file
-SRCSERV and -TGTSERV for specifying the source and target Exchange server(s) against which the export/import is performed
-D for displaying a progress window
-LOGMIN, -LOGMED and -LOGMAX for controlling the logging level
-NUMTHREADS for controlling the number of concurrent mailboxes processed

Typically I only use the -B and -F switches, passing all other settings through the INI file. The list of all possible INI file options is very long. The details are covered in the documentation included with ExMerge. So it is best to download (see references) and go through this document for more details.

The User Mailbox List

There are a few areas that tend to cause some difficulty when running ExMerge in batch mode. Here I am assuming ExMerge was installed successfully and that you are able to run the application through the Wizard. If you are having problems getting ExMerge to work, check Meeting the ExMerge Requirements. This takes you through the steps involved in getting ExMerge up and running.

Amongst other settings, ExMerge requires the list of mailboxes to be processed. These must be identified through their distinguished name (DN) and listed in a dedicated file typically named mailboxes.txt. The full path to this file must then be set within the configuration INI value 'FileContainingListOfMailboxes'.

The ExMerge documentation explains how to format this file exhaustively. What is usually a bit trickier is getting the distinguished names themselves. If you ran the ExMerge wizard and clicked on Save Settings, the list of mailboxes selected might be already waiting for you in mailboxes.txt under the directory where exmerge.exe is located. However, if at the wizard you selected all mailboxes, this file won't be created. Processing all mailboxes is the default behaviour and thus a list is not necessary. To generate the file, make sure to at least leave one mailbox unselected.

Use Save Settings now and look for mailboxes.txt.

Looking at a few distinguished names helps understanding their format. Often, identifying a new mailbox simply requires replacing the alias at the end of the DN.

In Windows 200x systems you can extract these values from Active Directory. Specifically each user account object (linked to an Exchange mailbox) will have the property legacyExchangeDN holding the required value. You could use adsiedit (included with the Windows 200x support tools), to read this for individual users.

Another option is the ldifde.exe command-line tool. This application is installed on Windows 200x servers. It is very useful when importing/exporting objects from Active Directory. Here I will just show an example of how ldifde.exe could be used for this purpose.

ldifde.exe -v -f c:\temp\users.txt -r "(& (objectclass=user)(mailnickname=*))" -l legacyExchangeDN -d CN=users,DC=domain,DC=com

The above command processes user objects under CN=users,DC=domain,DC=com. The exported objects are required to match the condition (& (objectclass=user)(mailnickname=*)). This filter is meant to only include users having an Exchange mailbox. The amount of information exported for each user is kept to a minimum through the -l legacyExchangeDN parameter sequence. Finally the exported data is saved to c:\temp\users.txt.

Here is how users.txt looks like:

Setting INI File Configuration Options Through Command-Line

Another aspect of ExMerge that can pose a little challenge is the setting of INI file values on the fly. Let's say ExMerge is part of a batch process performing a brick level backup. The generated pst files are to be saved in a directory whose name is constructed based on the date.

Using the configuration INI file this can be done by setting the DataDirectoryName value. However editing INI file values automatically is not that simple. For this purpose, I built a little application ExMergeIni.exe to do just that. Get your copy from the downloads section. For those having some programming background, this application boils down to calling the Win32 WritePrivateProfileString function.

With this application you can set any of the INI file values. Here is an example:

ExMergeIni.exe DataDirectoryName c:\ExMerge\Brick -f c:\ExMerge\Config.ini

The first parameter identifies the configuration setting name whereas the second identifies its value. The optional -f switch allows for specifying the path to the INI configuration file. For complete details on how to use the application just run it with no parameters.

Finally here is a little batch file example showing ExMergeIni.exe and ExMerge.exe in use together. This batch file takes one parameter specifying the path where the exported mailboxes and log files are to be saved. The script does include some hard-coded paths, but this is just for illustration purposes.

echo OFF
echo =================
echo = Backup Script =
echo =================
echo -
echo - Base Backup Destination Path: %1
if NOT EXIST %1 ( echo - FAILED: Invalid destination path. 
goto end )

echo ON

md %1\Exchange
md %1\Exchange\Brick 
md %1\Exchange\logs

C:\Backups\Script\ExMergeIni.exe DataDirectoryName %1\Exchange\Brick 
-f C:\Backups\Script\ExMerge.ini

C:\Backups\Script\ExMergeIni.exe LogFileName %1\Exchange\logs\ExMerge.log 
-f C:\Backups\Script\ExMerge.ini

"C:\Program Files\Exchsrvr\bin\ExMerge.exe" -b -f C:\Backups\Script\ExMerge.ini

echo OFF

:end
pause

Final Tips

Arguably the most useful interface exposed by ExMerge is the command-line. Through ldifde.exe, mailbox DNs may be retrieved to populate its list of mailboxes. ExMergeIni.exe facilitates batch processing, allowing the automatic adjustment of INI settings as necessary.

References

Meeting the ExMerge Requirements

ExMerge Download - Tools for Exchange Server 2003