Microsoft Exchange Agent

ExchangeAgent is the DirX Identity agent that handles the import and export of Exchange Mailboxes, Remote Addresses, and Distribution Lists to and from a Microsoft Exchange directory maintained on an Exchange server. ExchangeAgent supports Exchange V5.5; the Microsoft Exchange Server Administrator (admin.exe) must be used to import and export from older versions. ExchangeAgent uses the ADSI LDAP provider to bind to the Exchange server and runs on Windows.

ExchangeAgent can:

  • Perform a full or a delta export of Mailboxes, Remote Addresses and Distribution Lists from an Exchange directory, including multiple attribute values and using LDAP search filters

  • Perform a full or a delta import of Mailboxes, Remote Addresses and Distribution Lists into an Exchange directory, including multiple attribute values

  • Generate an import error file that records all Mailbox, Remote Address or Distribution List entries that it fails to import

  • Generate a log file (for tracing)

The following figures show the components of the ExchangeAgent export and import operations.

ExchangeAgent Export Components
Figure 1. ExchangeAgent Export Components
ExchangeAgent Import Components
Figure 2. ExchangeAgent Import Components

This section describes:

  • ExchangeAgent command line format for export and import operations

  • ExchangeAgent configuration files for export and import operations

  • The export data file format that ExchangeAgent generates

  • The import data file format that ExchangeAgent recognizes

  • ExchangeAgent import error file format

  • Exchange Server administration for import and export operations

Sample ExchangeAgent configuration files and scripts are provided in the \Samples\Exchange directory of the DirX Identity installation. See the file ExchangeReadme.txt for a description of these files and scripts.

You can also use Microsoft Exchange Server Administrator (admin.exe) to import Mailboxes, Remote Addresses, and Distribution Lists into an Exchange directory. See "Using Exchange Server Administrator" for information on how to use Administrator.

Command Line Format

The command line format to invoke ExchangeAgent is as follows:

ExchangeAgent.exe sync_switch data_file configuration_file
error_file [/a]>initial_error_file
[-Enc _encryption_mode -Timeout timeout_value -AuditLevel audit_level -CryptLogLevel crypt_level]

Parameters

sync_switch

Specifies the type of directory synchronization that ExchangeAgent is to perform. Possible values are:

/e Invokes the ExchangeAgent export function
/i Invokes the ExchangeAgent import function

data_file

For export: specifies the pathname of the target export data file that is to contain the entries that ExchangeAgent extracts from a Exchange directory.*
For import:* specifies the pathname of the source file that contains the data to be imported into an Exchange directory.

configuration_file

Specifies the name of the file that contains the specifications for the export and import procedure.

If the file is located in the working directory, you must explicitly indicate this fact by using the .\ notation before the file name, as shown in the example. It is not sufficient to specify only the file name, as it is for the data_file and error_file parameters.
error_file

Specifies the name of the file to which ExchangeAgent is to write error messages about errors that occur during the export or import process. For export errors, the format is:

###date_and_time command_line
Error! error_message
###date_and_time command_line

where error_message contains the function name that failed and an error code and error text.

For example:

### 06/07/2000 08:16:57 AM ExchangeAgent /e Data\ExportDirx.adr .\ExportDirx.ini ExportDirx.log
Error! ADsOpenObject failed. Error Code: 80005000 Error Text: An invalid Active Directory Pathname was passed.
### 06/07/2000 08:16:58 AM End

See "Import Error File Format" for a description of import error format.

/a (On export only)

Specifies that ExchangeAgent is to append the results of the export operation to data_file and error_file and write a timestamp at the start and end of the results. Use this switch on an export operation to append extracted entries to an existing export data file and to append error information to an existing error log file.

If the switch is not specified, ExchangeAgent overwrites the contents of the specified data_file and error_file, if they already exist.

initial_error_file

Specifies the name of the file to which ExchangeAgent is to write error messages for errors that occur before it creates error_file.

-ENC encryption_mode

Specifies the security mode. Valid modes are ATTRIB_ADMIN_PW or ADMIN_PW.

This function only works correctly in an appropriate security environment, such as the DirX Identity environment configured in security mode. (see the DirX Identity Connectivity Administration Guide for details).

-Timeout timeout_value

Specifies the timeout value for the security mode, in microseconds.

This function only works correctly in an appropriate security environment, such as the DirX Identity environment configured in security mode. (see the DirX Identity Connectivity Administration Guide for details).

-AuditLevel audit_level

Specifies the audit level value for the security mode. Valid values are in the range 0 through 4.

This function only works correctly in an appropriate security environment, such as the DirX Identity environment configured in security mode. (see the DirX Identity Connectivity Administration Guide for details).

-CryptLogLevel crypt_level

Specifies the logging level of the crypt library for the security mode. Valid values are greater or equal to 0.

This function only works correctly in an appropriate security environment, such as the DirX Identity environment configured in security mode. (see the DirX Identity Connectivity Administration Guide for details).

The following table describes the codes provided when ExchangeAgent.exe finishes running:

Exit Code Description

0

ExchangeAgent completed successfully.

1

ExchangeAgent completed with errors, which are described in the specified error_file unless this file cannot be created due to a file exception error.

60

ExchangeAgent completed with warnings, which are described in the specified error_file.

Configuration File Formats

ExchangeAgent uses the following configuration files:

  • Exchange export configuration file - controls the export of data from a Exchange directory

  • Exchange import configuration file - controls the import of data into a Exchange directory

See "General Structure of a Configuration File" for a description of the basic organization.

Templates of these configuration files are provided with the ExchangeAgent installation. The filenames are:

  • ExchExport.ini (to export all object classes (Mailboxes, Remote Addresses and Distribution Lists))

  • ExchImport.ini (to import all object classes (Mailboxes, Remote Addresses and Distribution Lists) from an import data file)

In general, you must customize these files to support the requirements of your Exchange import and export operations.

General Structure of a Configuration File

An ExchangeAgent configuration file consists of sections and fields defined within those sections. A configuration file has the following structure:

[SectionName]

+ <comment> _
sectionField_*=*fieldValue
.
.
.
[SectionName]

+ <comment>
sectionField=fieldValue
.
.
.

SectionName is a keyword enclosed in square brackets ([ ]) that identifies the purpose of the section. sectionField is a keyword that identifies the field and fieldValue is the value assigned to the section field, preceded by the equal sign (=). For example:

SearchScope=2

Comments can be inserted anywhere in an configuration file and are identified by any character - for example, a # character or a semicolon (;) - that appears at the beginning of a line.

Export Configuration File Format

The ExchangeAgent export configuration file consists of the following sections:

  • The Version section (required)

  • The Connection section (required)

  • The SearchPreferences section (optional)

  • The SearchFilter section (optional)

  • The SelAttributes section (optional)

  • The Attributes section (optional)

  • The Configuration section (optional)

  • The DeltaExport section (optional)

The next sections describe these sections.

The Version Section

The Version section consists of a single field that specifies the export configuration file version. The syntax is:

Version=version_number

where version_number is the version number assigned to the configuration file, in the format n.nn. The current version is:

Version=1.03

This is a mandatory field. This document describes the latest version of the ExchangeAgent export configuration file. The ExchangeAgent is able to process configuration files with version number 1.03 or lower as well as "old" files that do not contain a Version section. The following table provides information about the differences between export configuration file versions and about the support of older export configuration file versions for compatibility reasons:

"Old" 1.00 1.01 and higher

TraceLevel

Supported

Not supported

Not supported

Trace

Not supported

Supported (1)

Supported

LdapFilter

(2)

(1) TraceLevel has been replaced by Trace.
(2) If the field DeltaExport is set to 1, (USN-Changed>=*n)* must be specified in the LdapFilter field. (See The SearchFilter Section for details.)

The following new sections or section fields have been added to the specified version and do not conflict with older versions. These sections and fields are optional: if present, they are performed; if not, the default behavior is performed.

Version 1.02:
NTAccountFormat

The Connection Section

The Connection section is a mandatory section that consists of fields that define the parameters of an export operation for ExchangeAgent. The next sections describe these fields.

SearchBase

The SearchBase field specifies the base within the Exchange directory from which to export entries. The syntax is:

SearchBase=LDAP://host_name[:_port_number_][/distinguished_name]

where:

  • host_name specifies a computer name, an IP address, or a domain name.

  • port_number specifies the port on host_name on which the Microsoft Exchange LDAP server listens for requests. If port_number is not specified, ExchangeAgent uses the default LDAP port number 389.

  • distinguished_name specifies the name of the target Exchange directory root, in top-down (DAP-style) or bottom-up (LDAP-style) naming format.

For example:

SearchBase=LDAP://Saturn/O=MyCompany/OU=Talk1/CN=Recipients

Any comma (,) and forward slash (/) characters that are present in naming attribute values of distinguished_name must be "escaped" with the backslash character. For example:

SearchBase=LDAP://Venus/O=OpTech\, Inc./OU=Talk2/CN=Recipients

The SearchBase field is a mandatory field.

UserName

The UserName field specifies the NT account that ExchangeAgent is to use when binding to the Exchange server during the export procedure. The syntax is:

UserName=CN=*NT_account_name,CN=*NT_domain_name

For example:

UserName=cn=Smith,cn=TestDomain

The Exchange server retains deleted entries for a specific period of time (the default is 30 days, and can be changed by the Exchange administrator; see "Exchange Server Administration for Import and Export Operations" for further details). If your export procedure is to read extracted deleted entries from the Exchange directory, you must append the NT Administrator account name cn=admin to the values specified in the UserName field. For example:

UserName=CN=Smith,CN=TestDomain,CN=admin

The Exchange server must also be set up to enable ExchangeAgent to extract deleted entries from the Exchange directory; see "Exchange Server Administration for Import and Export Operations" for further details.

A recipient (Mailbox, Remote-Address and/or Distribution-List) can be hidden in an Exchange directory if its Hide-From-Address attribute is assigned the value True. To export hidden recipients, you must append the NT Administrator account name cn=admin to the values specified in the UserName field. For example:

UserName=CN=Beninga,CN=Saturn,CN=admin

This is an optional field; if it is not specified or is not present in the configuration file, ExchangeAgent uses the NT account that invoked it when binding to the Exchange server. If you specify a UserName field value, you must also specify a Password field value.

Password

The Password field specifies the password for the NT account name specified with the UserName field. The syntax is:

Password=password

For example:

Password=fidlajsks

This is an optional field; if no value is specified in this field or the field is not present in the configuration file, ExchangeAgent uses the password used with the NT account that invoked it when binding to an Exchange server during an export procedure. If you specify a Password field value, you must also specify a UserName field value.

UseSecureAuthentication

The UseSecureAuthentication field controls the level of authentication that ExchangeAgent uses when binding to an Exchange server during the export procedure. The syntax is:

UseSecureAuthentication=switch

where switch is one of the following values:

  • 0 - Use simple authentication (default)

  • 1 - Use secure authentication

The UseSecureAuthentication field is used in conjunction with the UseEncryption field to set the level of security services used during the export procedure. If UseSecureAuthentication is set to 1, the Exchange server managing the target Exchange directory must also have secure authentication enabled. See "Exchange Server Administration for Import and Export Operations" for further details.

UseEncryption

The UseEncryption field controls whether or not the Secure Socket Layer (SSL) port is used to provide a secure channel during the export procedure. The syntax is:

UseEncryption=switch

where switch is one of the following values:

  • 0 - Do not use SSL encryption (default)

  • 1 - Use SSL encryption

The UseEncryption field is used in conjunction with the UseSecureAuthentication field to set the level of security services used during the export procedure. Note that the SSL encryption setting on the Exchange server managing the target Exchange directory must match the UseEncryption setting specified in the configuration file. See "Exchange Server Administration for Import and Export Operations" for further details.

ADSI is designed to use simple binds when using SSL. Simple binds send UserName and Password in clear text across the network. Without using SSL this is not an acceptable method under security aspects, but using SSL the network traffic is encrypted and the UserName and Password are protected. Because ADSI does an anonymous bind when using NULL credentials in simple binds, which would result in not having sufficient permissions to view and modify objects in the Active Directory, we recommend the following combination of the flags if a secure connection is wanted:

Set the UseSecureAuthentication flag to 0 and the UseEncryption flag to 1 to establish a SSL connection and pass a UserName and a Password. Another possible method is to specify the SSL channel in the SearchBase, such as

LDAP://Saturn:636/O=MyCompany/OU=Identity/CN=Recipients

and also passing the UserName with a Password. This has the same effect as setting the UseEncryption flag.

The SearchPreferences Section

The SearchPreferences section is an optional section that consists of fields that specify parameters for search operations. The next sections describe these fields.

SearchScope

The SearchScope field specifies the search scope for search filters specified in the SearchFilter section. The syntax is:

SearchScope=number

where number is one of the following values:

  • 0 - Limits the search scope to the entry specified in the SearchBase field

  • 1 - Limits the search scope to the children of the entry specified in the SearchBase field

  • 2 - Limits the search scope to the subtree below the entry specified in the SearchBase field (default)

PageSize

The PageSize field controls how Microsoft Exchange server is to return search results to ExchangeAgent for a single search operation. The syntax is:

The syntax is:

PageSize=number

where number is one of the following values:

  • 0 - Processes the entire search result set before returning it to ExchangeAgent (default)

  • n - Processes and returns the search result in pages, where each page has a maximum of n entries. When a search results page contains n entries, Exchange server returns the page to ExchangeAgent.

You can use the PageSize field to maintain client-server performance in cases where large result sets are being processed and returned. Specifying a number in PageSize directs the Exchange server to process only that number of entries before returning the data to ExchangeAgent; this prevents large amounts of Exchange server memory from being tied up while the server acquires the search results data and allows for scalable search operations.

PagedTimeLimit

The PagedTimeLimit field controls the length of time that Microsoft Exchange server is to search for a single page. The syntax is:

The syntax is:

PagedTimeLimit=number

where number is one of the following values:

  • 0 - No time limit on the search of one page (default)

  • n - The maximum number of seconds to search for one page; specify a non-negative integer

AsynchronousSearch

The AsynchronousSearch field controls whether Microsoft Exchange server performs synchronous or asynchronous search operations. The syntax is:

AsynchronousSearch=switch

where switch is one of the following values:

  • 0 - A single search operation must complete before a new search operation can begin (default)

  • 1 - A new search operation can start while a current search operation is being processed

When AsynchronousSearch is set to 1, a new search can be started when the Exchange server returns the first entry. When a number in PageSize is specified and AsynchronousSearch is set to 1, a new search can be started when the Exchange server returns the first page of search results. If AsynchronousSearch is set to 0, a new search operation cannot be started until Exchange server returns the entire results set.

CacheResults

The CacheResults field controls whether ExchangeAgent caches search results in its local memory. The syntax is:

CacheResults=switch

where switch is one of the following values:

  • 0 - Do not cache results

  • 1 - Cache results (default)

TimeLimit

The TimeLimit field controls whether ExchangeAgent imposes a time limit for search results to be returned from Microsoft Exchange server. The syntax is:

TimeLimit=number

where number is one of the following values:

  • 0 - No time limit is imposed on search operations (default)

  • n - A time limit n is imposed on search operations, where n is the time in seconds after which ExchangeAgent is to abandon the search operation

The SearchFilter Section

The SearchFilter section is an optional section that specifies the Exchange entries that are to be exported from the Exchange directory and can control whether ExchangeAgent performs a delta export. The section consists of one or more LdapFilter fields. Each LdapFilter field specifies a collection of entries to locate and export. The syntax is as follows:

LdapFilter=filter

where filter is a search string specified in LDAP filter syntax; see RFC 2254 for an explanation of this syntax. For example:

LdapFilter=(objectClass=*)

The following table shows some sample LDAP filters and their results.

Filter Value Action Taken

(objectClass=*)

Export all entries

(objectClass=organizationalPerson)

Export all Mailbox entries

(objectClass=Remote-Address)

Export all Remote Address entries

(&(objectClass=*) (sn=a*))

Export all entries whose surname begins with "a"

(&(objectClass=organizationalPerson) (postalAddress=*))

Export all Mailbox entries that have the attribute postalAddress set

(&(objectClass=*) (Is-Deleted=True))

Export all deleted entries

(&(objectClass=*) (USN-Changed>=6200))

Export all entries whose USN-changed value is higher than the latest USN-changed value (delta export)

When specifying attributes in filter, you must use the LDAP names for the attributes. See "Microsoft Exchange Directory Schema" for tables of LDAP name-to-Exchange name mappings.

ExchangeAgent creates one export data file. If the DeltaExport field in the DeltaExport section is set to 0, this file contains all of the entries extracted from the Exchange directory that match the search criteria specified in the SearchPreferences and SearchFilter sections. This file is called the "export data file" (or "full export data file").

ExchangeAgent uses the LdapFilter field in conjunction with the Delta Export fields DeltaExport (set to 1) and the USNChangedMax field to create a search filter that performs a "delta" export of modified entries into the generated export data file. See the DeltaExport section for further details.

The Exchange server retains deleted entries for a specific period of time (the default is 30 days, and can be changed by the Exchange administrator; see "Exchange Server Administration for Import and Export Operations" for further details). For deleted entries, it updates the "Is-Deleted" Exchange attribute to TRUE. Use the "Is-Deleted" Exchange attribute as a search filter component to direct ExchangeAgent to extract deleted entries into the generated export data file. Note that ExchangeAgent can only extract and read deleted entries if the Exchange server that is managing the target directory has been set up with the appropriate access rights. See "Exchange Server Administration for Import and Export Operations" for further details.

Because ExchangeAgent always generates only one export data file, it is recommended that you perform separate export operations to extract modified entries and deleted entries. (If the search filter supplied in LdapFilter selects both modified and deleted entries, they are written to the same export data file.)

Only one LDAP search filter can be activated per export operation.

This is an optional field. If no value is specified or the field is not present in the configuration file, ExchangeAgent exports all entries.

The SelAttributes Section

The SelAttributes section is an optional section of the export configuration file that controls whether or not ExchangeAgent retrieves all entry attributes with a value, or only those attributes set to 1 in the Attributes section. The section consists of one field, which is SelectAttributes. The syntax is:

SelectAttributes=switch

where switch is one of:

  • 0 - Export all attributes with a value (default)

  • 1 - Export only those attributes set to 1 in the Attributes section

This field must be set to 1 to perform a delta export operation. See the DeltaExport section for more information about the delta export operation.

The Attributes Section

The Attributes section is an optional section of the export configuration file that specifies a set of Exchange attributes to be exported from an Exchange directory. The syntax is:

attribute_name=switch

where attribute_name is the name of an Exchange attribute and switch is one of the following values:

  • 0 - Do not export the attribute value for attribute_name

  • 1 - Export the attribute value for attribute_name

For example:

[Attributes]
#Attributes specific to Remote Addresses
#
Target-Address=1
userPassword=0
#
#Attributes specific to Distribution Lists
#
DL-Member-Rule=0
Hide-DL-Membership=0
member=1
OOF-Replay-To-Originator=0
owner=0
Report-To-Owner=0
#

Use the switch parameter to select or exclude attributes in the list for export.

If the Attributes section is not specified in the configuration file and SelectAttributes is set to 0 in the SelAttributes section, ExchangeAgent exports all of the attributes of Exchange entries that match the search criteria specified in the SearchPreferences and SearchFilter sections. If SelectAttributes is set to 1 and the Attributes section does not contain any attributes that are set to 1, nothing is exported.

Note that the USN-Changed attribute must be set to 1 in the Attributes section in order to perform a delta export operation. See the DeltaExport section for more information about delta export operations.

The Configuration Section

The Configuration section is an optional section that contains information that ExchangeAgent is to use when evaluating entry attributes during the export procedure. The next sections describe the fields in the Configuration section.

MultiValueSeparator

The MultiValueSeparator field specifies a value to be used to separate the individual attribute values of a multi-valued attribute. The syntax is:

MultiValueSeparator=[character]

where character is a character or a string used as a multi-valued attribute separator. For example:

MultiValueSeparator=#

This field is optional. If it is not specified (or not present in the configuration file), ExchangeAgent uses the pound sign (#) as the multi-valued attribute separator.

Trace

The Trace field controls whether ExchangeAgent performs program flow tracing on an export operation. The syntax is:

Trace=[switch]

where switch is one of the following values:

  • 0 - Do not perform program flow tracing on the export operation (default)

  • 1 - Perform program flow tracing on the export operation

If 1 is specified, ExchangeAgent writes information about the export operation to the pathname specified in the TraceFileName field.

TraceFileName

The TraceFileName field specifies the pathname of the trace file to which ExchangeAgent is to write information about the export operation. The syntax is:

TraceFileName=pathname

where pathname is the name for the trace file. For example:

TraceFileName=c:\Exchsync\ExportTraceFile

This field is optional unless Trace is set to 1. ExchangeAgent does not evaluate this field if Trace is set to 0.

NTAccountFormat

The NTAccountFormat field controls the format in which the attribute Assoc-NT-Account is exported. The syntax is:

NTAccountFormat=format

where format is one of the following values:

  • Text - The Assoc-NT-Account is exported in the format domain_name_user_name_ (default)

  • Hex - The Assoc-NT-Account is exported as a hex string.

The DeltaExport Section

The DeltaExport section is an optional section that provides information that can be used to direct ExchangeAgent to perform a delta export of entries from the Exchange directory.

The next sections describe the fields in the DeltaExport section.

DeltaExport

The DeltaExport field controls whether ExchangeAgent performs a full or delta export of the Exchange directory. The syntax is:

DeltaExport=[switch]

where switch is one of the following values:

  • 0 - Export all entries (or those entries specified with the LDAPFilter field) from the directory (default)

  • 1 - Export only those entries whose USN-Changed attribute value is greater than or equal to the value of the USNChangedMax field.

If the DeltaExport field is set to 1:

  • The Delta Export section must contain the USNChangedMax field and value

  • The Attributes section must specify the USN-Changed attribute set to 1

  • The SelectAttributes field in the SelAttributes section must be set to 1

This is an optional field. If it is not specified (or the field is not present in the configuration file), ExchangeAgent exports all entries in the directory (or all the entries selected using the specifications in the LDAPFilter field, if it is present in the configuration file) from the Exchange directory.

USNChangedMax

The USNChangedMax field specifies the highest-numbered USN-changed attribute value in the Exchange directory. The syntax is:

USNChangedMax=USN

where USN is an integer that represents the highest-number USN assigned to an Exchange container entry in the directory. For example:

USNChangedMax=6426

The USN-Changed attribute is a Microsoft Exchange attribute that is assigned to every entry in the Exchange directory. When the Exchange server carries out a modification to an entry, it assigns the highest USN to the entry’s USN-Changed attribute as its value.

For the initial delta export, you must:

  • Set the value of USNChangedMax to 0:

  • Set the DeltaExport field to 1

ExchangeAgent selects only those entries modified after the value provided in the USNChangedMax field (all entries, in this export run). When it completes the export, ExchangeAgent updates the USNChangedMax field with the current highest USN-Changed attribute value.

On subsequent exports, each time ExchangeAgent performs an export and the DeltaExport field is set to 1, it automatically appends the string USN-Changed³USN to the filter specified in the LdapFilter field, where USN is the current value in the USNChangedMax field. It then performs the export and updates the USNChangedMax field with the current highest USN-Changed attribute value.

Performing incremental delta exports works only if you do not change the search filters or the attributes in the export configuration file. If you make changes to search filters in the SearchFilter section or to the attribute list in the Attributes section, you will need to perform a full export and re-set the USNChangedMax attribute.

Import Configuration File Format

The ExchangeAgent import configuration file consists of three sections:

  • The Version section (required)

  • The Connection section (required)

  • The Configuration section (optional)

  • The Ignore Empty Attributes section (optional)

  • The Encrypted Attributes section (optional)

  • The AttributeTypes section (required)

The Version Section

The Version section consists of a single field that specifies the import configuration file version. The syntax is:

Version=version_number

where version_number is the version number assigned to the configuration file, in the format n.nn. The current version is:

Version=1.03

This is a mandatory field. This document describes the latest version of the ExchangeAgent import configuration file. The ExachangeAgent is able to process configuration files with version number 1.03 or lower as well as "old" files that do not contain a Version section. The following table provides information about the differences between import configuration file versions and about the support of older import configuration file versions for compatibility reasons:

"Old" 1.00 1.01 and higher

TraceLevel

Supported

Not supported

Not supported

Trace

Not supported

Supported (1)

Supported

SearchBase

Not supported

Not supported

Supported

(1) TraceLevel has been replaced by Trace.

The following new sections or section fields have been added to the specified version and do not stay in conflict to older versions. These sections and fields are optional: if present, they are performed; if not, the default behavior is performed.

Version 1.02:
CreateNTAccounts
DeleteNTAccounts
[IgnoreEmptyAttrValues]

The Connection Section

The Connection section is a mandatory section that consists of fields that define the parameters of an import operation for ExchangeAgent. The next sections describe these fields.

UserName

The UserName field specifies the NT account that ExchangeAgent is to use when binding to the Exchange server during the import procedure. It has the same syntax as the UserName field in the export configuration file.

A recipient (Mailbox, Remote-Address and/or Distribution-List) can be hidden in an Exchange directory if its Hide-From-Address attribute is assigned the value True. To modify hidden recipients on import, you must append the NT Administrator account name cn=admin to the values specified in the UserName field. For example:

UserName=CN=Beninga,CN=Saturn,CN=admin

Deleting hidden recipients does not require the cn=admin privilege.

Password

The Password field specifies the password for the NT account name specified with the UserName field. It has the same syntax as the Password field in the export configuration file.

UseSecureAuthentication

The UseSecureAuthentication field controls the level of authentication that ExchangeAgent uses when binding to an Exchange server during the import procedure. It has the same syntax as the UseSecureAuthentication field in the export configuration file.

UseEncryption

The UseEncryption field controls whether or not the Secure Socket Layer (SSL) port is used to provide a secure channel during the import procedure. It has the same syntax as the UseEncryption field in the export configuration file.

SearchBase

The SearchBase field specifies the base within the Exchange directory from which to export entries. The syntax is:

SearchBase=LDAP://host_name[:_port_number_][/distinguished_name]

where:

  • host_name specifies a computer name, an IP address, or a domain name.

  • port_number specifies the port on host_name on which the Microsoft Exchange LDAP server listens for requests. If port_number is not specified, ExchangeAgent uses the default LDAP port number 389.

  • distinguished_name specifies the name of the target Exchange directory root, in top-down (DAP-style) or bottom-up (LDAP-style) naming format.

    For example:

    SearchBase=LDAP://Saturn/O=MyCompany/OU=Talk1/CN=Recipients

    Any comma (,) and forward slash (/) characters that are present in naming attribute values of distinguished_name must be "escaped" with the backslash character. For example:

    SearchBase=LDAP://Venus/O=OpTech\, Inc./OU=Talk2/CN=Recipients

    The SearchBase field is a mandatory field when the import data file uses the "ldapFilter" attribute.

The Configuration Section

The Configuration section is an optional section that consists of fields that contain information that ExchangeAgent is to use when evaluating entry attributes in an import data file. The next sections describe these fields.

MultiValueSeparator

The MultiValueSeparator field specifies a value to be used to separate the individual attribute values of a multi-valued attribute. The syntax is the same as the MultiValueSeparator field in the export configuration file.

IgnoreObjectClass

The IgnoreObjectClass field controls whether ExchangeAgent evaluates or ignores the ObjectClass attribute of entries for which the "modify" LDIF changetype operation has been specified. The syntax is:

IgnoreObjectClass=switch

where switch is one of the following values:

  • 0 - Evaluate the ObjectClass attribute when the changetype operation is "modify"

  • 1 - Ignore the ObjectClass attribute when the changetype operation is "modify" (default)

Exchange server does not currently permit the modification of the ObjectClass attribute through an LDIF "changetype" operation. Consequently, you can set the IgnoreObjectClass field to 1 to direct ExchangeAgent not to pass the ObjectClass attribute to the Exchange server. However, other LDAP servers that manage Exchange directories do permit the modification of the ObjectClass attribute. Setting IgnoreObjectClass to 0 in these cases permits ExchangeAgent to pass the ObjectClass attribute to the LDAP server for evaluation.

Trace

The Trace field controls whether ExchangeAgent performs program flow tracing on an import operation. It has the same syntax as the Trace field in the export configuration file and is an optional field.

TraceFileName

The TraceFileName field specifies the pathname of the trace file to which ExchangeAgent is to write information about the import operation. It has the same syntax as the TraceFileName field in the export configuration file and is an optional field unless the Trace field is specified.

RejectSpecialCharacters

The RejectSpecialCharacters field controls whether ExchangeAgent evaluates the ADsPath attribute of entries in the import data file for special characters. The syntax is:

RejectSpecialCharacters=switch

where switch is one of the following values:

  • 0 - Do not evaluate the ADsPath attribute for special characters (default)

  • 1 - Evaluate the ADsPath attribute for special characters

If 1 is specified, ExchangeAgent scans the Common-Name (cn) RDN of each import entry’s ADsPath attribute for the characters specified in the RejectedCharacters field and rejects the entry for import if it contains one of these characters.

Use this field in conjunction with the RejectedCharacters field if you are working with Microsoft Exchange server 5.5; these fields provide a "work around" to a bug that exists in this version of Exchange server. For more information about the bug and its recommended resolution, see the URL:

http://support.microsoft.com/support/kb/articles/q222/6/47.asp

RejectedCharacters

The RejectedCharacters field specifies the characters in the import entries' AdsPath attribute that ExchangeAgent is to scan for; ExchangeAgent is to reject the entry for import if it contains one of these characters. The syntax is:

RejectedCharacters=characters

Where characters specifies the characters in the Common-Name RDN of the AdsPath attribute for which ExchangeAgent is to search.

This field is optional unless RejectSpecialCharacters is set to 1. ExchangeAgent does not evaluate this field if RejectSpecialCharacters is set to 0.

CreateNTAccounts

The CreateNTAccounts field controls whether ExchangeAgent creates an NT-Account if the attribute NT-Account is specified in the data record or if it only tries to assign this NT-Account to the mailbox. The syntax is:

CreateNTAccounts=switch

where switch is one of the following values:

  • 0 - Don’t create the NT-Account if it does not exist

  • 1 - Create the NT-Account if it does not exist (default)

If 1 is specified, ExchangeAgent creates the NT-Account if the attribute NT-Account is specified in the data record and if the account does not exist yet. If 0 is specified, ExchangeAgent tries to assign the specified account to the mailbox, but does not create it if the assignment fails.

DeleteNTAccounts

The DeleteNTAccounts field controls whether ExchangeAgent deletes an NT-Account when deleting the mailbox if the attribute NT-Account is specified in a data record with changetype delete. The syntax is:

DeleteNTAccounts=switch

where switch is one of the following values:

  • 0 - Don’t delete the NT-Account when deleting the mailbox

  • 1 - Delete the NT-Account when deleting the mailbox (default)

If 1 is specified, ExchangeAgent deletes the NT-Account when deleting the mailbox if the attribute NT-Account is specified in a data record with changetype delete. If 0 is specified, ExchangeAgent does not delete the specified NT-Account.

The Ignore Empty Attributes Section

The Ignore Empty Attributes section is an optional section that lists attributes which are ignored if they exist in the import data file and if they are empty. Normally an attribute with an empty value results in clearing that attribute in the Active Directory. The attributes are listed in the format:

name_of_attribute=1

where name_of_attribute is the name for the attribute to be imported.

For example:

  • [IgnoreEmptyAttrValues]
    NT-Account=1
    Submission-Cont-Length=1

The Encrypted Attributes Section

The Encrypted Attributes section is an optional section that lists attributes that are encrypted in the import data file and which must be decrypted by ExchangeAgent before they are passed to the Adsi interface. This function only works correctly in an appropriate security environment, such as the DirX Identity environment configured in security mode (see the DirX Identity Connectivity Administration Guide for more information). The attributes are listed in the format:

name_of_attribute=1

where name_of_attribute is the name of the attribute to be imported.

For example:

  • [EncryptedAttributes]
    description=1

The Attribute Types Section

The Attribute Types section is a mandatory section that specifies the attribute syntax for each Exchange attribute to be imported into the Exchange directory. The section consists of one or more attribute syntax specifications in the format:

LDAP_name_of_attribute=attribute_syntax

where LDAP_name_of_attribute is the LDAP name for the Exchange attribute to be imported and attribute_syntax is one of the following keywords:

  • Boolean
    CaseExactString
    CaseIgnoreString
    DNstring
    Integer
    LargeInteger
    NumericString
    ObjectClass
    OctetString
    PrintableString
    ProviderSpecific
    UTCTime

Each of these keywords corresponds to a data type that can be passed over the Active Directory Services Interface (ADSI). Because ExchangeAgent uses this interface, it must specify the data type of each attribute it passes over the interface. The Attribute Types section provides ExchangeAgent with the information it needs about each attribute’s ADSI data type.

For example:

[Attribute Types]
changetype=CaseIgnoreString
objectClass=CaseIgnoreString
Company=CaseIgnoreString
cn=CaseignoreString
department=CaseIgnoreString
member=DNString
Replication-Sensitivity=Integer
Report-To-Originator=Boolean

Export and Import Data File Format

The ExchangeAgent import and export data files use a tagged file format. The next sections describe the:

  • General characteristics of export and import data file formats

  • Specific features of the import data file format

General Data File Format

The ExchangeAgent import and export data files have the following characteristics:

  • Each entry attribute is contained on one line; line continuation is not permitted.

  • The representation of each attribute is: attribute_name:_attribute_value(s)_

  • Leading and trailing whitespace between attribute_name and attribute_value is ignored. For example, in the attribute:

           cn: SallyAnn K. Quebec

    The whitespace between the colon (:) and the start of the attribute value is ignored, but the whitespace within the attribute value is returned.

  • The form-feed character (0x0c) is used as a record (entry) separator

  • The form-feed character can optionally appear as the first line in the file

  • There is no special character processing (there is no "escaping" mechanism)

Here is an example:

(0x0c is here as a record (entry) separator)
changetype: delete
objectClass: Remote-Address
cn: Robert Amber
rdn: Robert Amber
Replication-Sensitivity: 20
telephoneNumber: 603 555 8845
uid: AliasAmber
givenName: Robert
l:Nashua, New Hampshire
postalAddress: 110 Spitbrook Road
postalCode: 03060
sn: Amber
Target-Address: SMTP:robert_amber@spitbrook.digital.com
(0x0c is here as the record (entry) separator)
...

"Microsoft Exchange Directory Schema" describes the Microsoft Exchange directory schema.

Import Data File Format

ADsPath

Individual entries in a single import data file can be targeted for import to different containers or Exchange servers. Consequently, each entry in an ExchangeAgent import data file must contain an ADsPath attribute that identifies the fully-qualified pathname of the Remote Address, Distribution List, or Mailbox entry to be added, modified, or deleted. The attribute syntax is:

ADsPath:LDAP://host_name[:_port_number_][/distinguished_name]

where:

  • host_name specifies a computer name, an IP address, or a domain name.

  • port_number specifies the port on host_name on which the Microsoft Exchange LDAP server listens for requests. If port_number is not specified, ExchangeAgent uses the default LDAP port number 389.

  • distinguished_name specifies the name of the target Exchange directory root, in top-down (DAP-style) or bottom-up (LDAP-style) naming format.

For example:

ADsPath=LDAP://Mars/O=MyCompany/OU=Talk1/CN=Recipients/CN=Arno Held

ldapFilter

The ExchangeAgent import data file format also supports a per-entry ldapFilter attribute. The value of this attribute is a search filter that specifies an attribute that acts as a unique key for matching the entry in the import data file with an entry in an Exchange Directory. The attribute syntax is:

ldapFilter: filter

where filter is a search string specified in LDAP filter syntax (see RFC 2254 for an explanation of this syntax) that uses an attribute as a unique identifier. For example:

ldapFilter: (&(objectClass= Remote-Address)(uid=Held))

It is recommended to use the uid attribute as the unique key in the ldapFilter attribute; however, other attributes can be defined and used as keys. When a "modify" or "delete" entry (see the per-entry changetype description ) in the import data file contains an ldapFilter attribute, and an ADsPath attribute is not present, ExchangeAgent uses the ldapFilter attribute to search the Exchange Directory specified in the SearchBase field using the scope specified in the SearchScope field (or the default). If ExchangeAgent finds one entry that matches the filter criteria, ExchangeAgent modifies or deletes the entry, according to its changetype attribute. If ExchangeAgent finds more than one matching entry, or does not find a matching entry at all, it writes an error to the import error file.

Per-Entry Changetype

The ExchangeAgent import data file format also supports the LDIF per-entry "changetype" attribute that indicates the type of modification to be made to the entry in the Exchange directory and the attribute operation codes "add" or "delete". The value for "changetype" is one of "add", "modify", or "delete". The changetype attribute name and its values are case-insensitive and can appear anywhere in the entry. If a changetype attribute is not present (or does not contain a value), ExchangeAgent attempts an "add" operation for the entry. If the "add" operation fails with the error code "entry already exists", it attempts a "modify" operation.

As with all other entries in an import data file, entries that contain changetype attributes must contain the ADsPath attribute. Entries with a "modify" changetype attribute value must also contain at least one attribute to be modified. If the modify operation fails with the error code "no such object", ExchangeAgent attempts to find the object using the ldapFilter attribute (if present) and then performs the modify operation. Entries with an "add" changetype must contain an object class attribute. For a "modify" operation, attributes can be deleted either by setting their values to an empty string or by setting them to the string <clear>.

Mandatory Attributes

Depending on the object class attribute value, the following attributes must also be present in the entry:

  • For Remote Addresses (objectClass=Remote-Address), the attributes cn, uid, sn, Target-Address, textEncodedORaddress, Hide-From-Address-Book, MAPI-Recipient, Replication-Sensitivity, and rfc822Mailbox must be present

  • For Distribution Lists (objectClass=groupOfNames) the attributes cn, member, Hide-DL-Membership, Hide-From-Address-Book, Replication-Sensitivity, rfc822Mailbox, and textEncodedORaddress must be present

  • For Mailboxes (objectClass=organizationalPerson), the attributes cn, uid, sn, Assoc-NT-Account, Home-MDB, Home-MTA, mailPreferenceOption, MDB-Use-Defaults, MAPI-Recipient, Replication-Sensitivity, rfc822Mailbox, and textEncodedORaddress must be present

Multi-valued Attributes and Operation Codes for Attributes

The attributes for a multi-valued attribute appear on one line and are separated by the multi-valued attribute separator specified in the MultiValueSeparator field in the import configuration file. For example:

...
member: cn=Test1,cn=Recipients,ou=identity1,o=MyCompany#cn=Test2,cn=Recipients,ou=identity1,o=MyCompany#cn=Test3,cn=Recipients,ou=identity1,o=MyCompany

For entries with a "modify" changetype, the specified attributes are overwritten with the new value and the other attributes retain their old value. If an operation code for an attribute is specified, values for this attribute can be added or deleted. A sample for the syntax is given for the following entry:

changetype: modify
ADsPath: LDAP://IdentityServ2000/CN=Arno Held,CN=Recipients,
     OU=identity1,O=MyCompany
sn: Held
add: member
member: cn=Test4,cn=Recipients,ou=identity1,o=MyCompany
delete: member
member: cn=Test1,cn=Recipients,ou=identity1,o=MyCompany#cn=Test2,
    cn=Recipients,ou=identity1,o=MyCompany
Comments

The import data file can contain comments, which are identified by a # character at the beginning of a line.

Assoc-NT-Account Attribute

Mailbox entries to be imported can contain the Assoc-NT-Account pseudo attribute, which ExchangeAgent uses to assign an NT account to a mailbox entry to be added. The attribute has the syntax:

Assoc-NT-Account: domain\user

where domain is the domain name and user is the user account name. For example:

Assoc-NT-Account: ASW\Testuser

ExchangeAgent uses the domain name and user account name to create the LDAP attributes Assoc-NT-Account and NT-Security-Descriptor and then passes these attributes to the Exchange server. The attribute syntax for these LDAP attributes is OctetString, for example, 00515000000EE490F6B657A1E603031. The attribute Assoc-NT-Account is represented in the export data file in the form: domain\user or in the OctetString form if specified so (hex string) in the export.ini file.

Attributes of Type OctetString

If an attribute in the import.ini file is specified with the OctetString, data type, ExchangeAgent expecteds it to be base64 encoded in the import data file. In export direction, ExchangeAgent writes attributes with type OctetString in Base64 encoding into the export data file.

Import Error File Format

During the import process, ExchangeAgent writes the original attributes and values of Remote Address, Distribution List, or Mailbox entries that it is unable to import into the error file specified on the command line along with an error message that describes the error that caused the import to fail on the entry. Each error record in the import error file has the following format:

  • #warning_message
    source_entry
    #error_message

Where warning_message contains a warning text, source_entry is the original entry that ExchangeAgent was unable to import and error_message contains the function name that failed and an error code and error text. Entries can have either warning_message or error_message or both of them. For example:

#Warning! Cannot find Attribute Type of xxx. Attribute Ignored.
changetype: add
objectClass: organizationalPerson
ADsPath: LDAP://Premium:390/o=MyCompany/ou=identity1/cn=Recipients/cn=Marc Held0
cn: DisplayMBHeld0
uid: Marc Held0
sn: Held0
xxx: test
NT-Account: ASW\Testuser
Home-MDB: cn=Microsoft Private MDB,cn=ExchServer1,cn=Servers,cn=Configuration,ou=identity1,o=MyCompany
Home-MTA: cn=Microsoft MTA,cn=ExchServer1,cn=Servers,cn=Configuration,ou=identity1,o=MyCompany
mailPreferenceOption: 0
MDB-Use-Defaults: True
MAPI-Recipient: True
Replication-Sensitivity: 20
rfc822Mailbox: marc.held2@icn.mycompany.de
textEncodedORaddress: c=de;a=abc;p=MyCompany;o=identity1;s=Held2;
#Error! CreateDSObject of LDAP://Premium:390/o=MyCompany/ou=identity1/cn=Recipients/cn=Marc Held0 failed. Error Code: 80071392 Error Text: The object already exists.

Any entry that cannot be imported into the Exchange directory is written into the import error file. Consequently, you can use the error file as an input file and re-run the import operation, after first fixing the errors reported in the file. A timestamp is written at start and end of the error file.

ExchangeAgent Import Notes

Each mailbox in Exchange is associated with an NT account. As part of the import procedure, ExchangeAgent manages the NT accounts associated with mailboxes as follows:

  • When ExchangeAgent creates a mailbox and the NT-Account attribute is present in the import entry and did not previously exist and the CreateNTAccounts field is not set to 0 in the import.ini file, it creates an NT account and associates it with the mailbox. This operation is performed for import entries with no changetype attribute and for entries whose changetype attributes are "add" or "modify". For the operations creating and associating NT accounts to succeed:

    • the machine running ExchangeAgent must be a member of a domain that trusts all domains from which NT accounts are to be assigned

    • the Windows/NT Logon procedure must be carried out using an account that has the rights to create NT accounts in the specified domain.

    • the Windows/NT Logon procedure must be carried out using an account that has the rights to carry out security functions in the domain the machine running the ExchangeAgent is a member of.

  • When ExchangeAgent deletes a mailbox (because the import entry has the changetype attribute "delete") and the NT-Account attribute is present in the import entry and the DeleteNTAccounts field is not set to 0 in the import.ini file, it deletes the associated NT account. To prevent the associated NT account from being deleted either set the DeleteNTAccounts field to 0 resulting in preventing the deletion for all associated NT accounts or make sure you filter out the attribute in your mapping procedure. If the NT-Account attribute is not present in the import entry, ExchangeAgent deletes only the mailbox.

  • When ExchangeAgent modifies a mailbox and the NT-Account attribute is present in the import entry, it associates the mailbox with the NT account specified in the attribute. This operation is performed for import entries with no changetype attribute and for entries with the changetype attribute "modify".

In order for ExchangeAgent to perform these operations on NT accounts, the Exchange server Service account must be set up with "Service Account Admin" rights. Refer to the section "Enabling NT Account Management during Import Operations" in the sections that follow. ExchangeAgent can only automatically create and associate NT accounts with Exchange mailboxes; it cannot automatically create Windows 20xx or Active Directory accounts and associate them with Exchange mailboxes. It also cannot create a mailbox that is associated with a Windows 20xx or Active Directory account.

When importing mailboxes that are to be accessed from POP3 clients:

  • The NT account associated with the mailbox must be identical to the mailbox aliasname attribute value (which is a UID)

  • The POP3 client must use the mailbox aliasname as the logon name

Exchange Server Administration

The administrator of an Exchange server that is to be the target of an ExchangeAgent import or export operation may need to perform some administrative tasks on the server to ensure proper operation of the ExchangeAgent import and/or export procedure. The next sections describe how to:

  • Manage the Exchange Server’s LDAP Interface

  • Export Deleted Entries

  • Set the Tombstone Lifetime for Deleted Entries

  • Monitor LDAP Operations on the Exchange Server

  • Enable NT Account Management during Import Operations

Managing the Exchange Server’s LDAP Interface

ExchangeAgent accesses the Exchange server through its LDAP interface. Consequently, the administrator of an Exchange server that is to be the target of an ExchangeAgent export or import operation should ensure that the server is accessible through its LDAP interface.

Next, the administrator should ensure that the settings for the LDAP interface correspond to the requirements of the ExchangeAgent import and export configurations in the following areas:

  • The port number set for the Exchange server must match the port number specified in the SearchBase field of the export configuration file

  • The authentication method selected in the UseSecureAuthentication field of the export or import configuration files must be enabled in the Exchange server

  • The maximum number of entries returned for a single search must be large enough to accommodate the number of entries to be exported in an ExchangeAgent export operation

Use the Exchange Server Administrator (admin.exe) to manage the Exchange server’s LDAP settings:

  • Select container Organization → Site → Configuration → Protocols, and then select Properties.

  • Select General to check and change the Exchange server port number.

  • Select Authentication to check and change the authentication methods (the default is no authentication; this selection does not need to be changed if the UseSecureAuthentication field is set to 0 (no authentication)

  • Select Search to check and change the maximum number of entries returned in a search result (the default is 100 entries)

If you do not want to inherit Site Protocol settings, you can use the Ldap-Protocol menu of the Server container to check and change the LDAP settings.

The Exchange server must be restarted after changing any LDAP settings.

Exporting Deleted Entries

To enable ExchangeAgent to extract and read deleted entries from an Exchange directory, the Exchange server that manages the target Exchange directory must be administered as follows:

  • The Exchange server Service on the NT system that is running the target Exchange server must be started with an NT account that is a member of the Administrators local group.

  • The Exchange server Service account must be set up with "Service Account Admin" rights. To establish these rights, use Exchange Server Administrator (admin.exe) as follows:

  • Open Properties of the Site container

  • Select Permissions

  • Add the Exchange server Service account

  • Select "Service Account Admin" rights for the account

  • The NT account that is running the ExchangeAgent export procedure (the account that is specified in the UserName and Password fields of the export configuration file) must be granted "Admin" rights on the target Exchange server. To grant these rights, use Exchange Server Administrator (admin.exe) as follows:

  • Open Properties of the Site container

  • Select Permissions

  • Add the ExchangeAgent NT account

  • Select "Admin" rights for the account

In addition to the Exchange server setup just described, the NT account specified in the UserName field must be appended with cn=admin. For example:

UserName=CN=Smith,CN=TestDomain,CN=admin

Setting the Tombstone Lifetime for Deleted Entries

The Exchange server retains deleted entries and attributes for the period of time specified in its Tombstone Lifetime property. The default time period is 30 days and can be changed using Exchange Server Administrator (admin.exe) as follows:

  • Select the container Organization → Site → Configuration

  • Select Properties of DS Site Configuration

  • Select General, and then set Tombstone Lifetime

Monitoring LDAP Operations on the Exchange Server

The administrator of an Exchange server that is the target of ExchangeAgent import and export operations can enable LDAP logging in the Exchange server to monitor incoming LDAP operations, in cases where ExchangeAgent import or export operations are not returning the expected results. To enable LDAP logging, use Exchange Server Administrator (admin.exe) as follows:

  • In the Servers container, open Properties of the Exchange server

  • Select Diagnostics Logging

  • Select MSExchangeDS, LDAP Interface, and the maximum logging level in Logging Level

Use the Event Viewer to review the LDAP logging information returned by the Exchange server.

Enabling NT Account Management during Import Operations

To enable ExchangeAgent to manage the NT accounts associated with mailboxes during its import procedure, the Exchange server Service account must be set up with "Service Account Admin" rights. To establish these rights use Exchange Server Administrator (admin.exe) as follows:

  • Open Properties of the Site container

  • Select Permissions

  • Add the Exchange server Service account

  • Select "Service Account Admin" rights for the account