OABInteg and how to use it to troubleshoot OAB generation issues.
7th Feb 2006, 16:45 GMT
With all of the extensive troubleshooting and debugging that I have done over the last year for OAB generation process, I thought it would be worth while to write an tool that could help customers troubleshoot these issues. The OAB generation process is unknown to many, so I have felt the need to starting posting about it. This tool is now being used extensively by some of the biggest premier enterprise and hosting customers in the US and in Europe. I am glad to say that this tool is now available for download, and is no longer an internal only support tool. There is also a public kb article for the tool http://support.microsoft.com/?id=907792 - Description of the Offline Address Book Integrity (OABInteg) tool. The tool can be downloaded from the following location: http://gotdotnet.com/Community/UserSamples/Download.aspx?SampleGuid=A2338E73-F521-4071-9B1D-AAF49C346ACD . I want to thank two people for posting documentation on OABInteg. 1. Henrik Walther for taking the time to write up an article on OABInteg. The article can be found here. Henrik is a Microsoft Exchange MVP and author for www.exchange-faq.dk. 2. Matt Richoux who created the webcast on "How to troubleshoot Offline Address Book issues in Microsoft Exchange Server". This web cast contains information on OABInteg and it's usage. If you missed this web cast, you can go here for more information: http://support.microsoft.com/default.aspx?scid=kb;en-us;905482 . Overview This document covers the Offline Address Book Integrity (OABINTEG) tool, which can be very useful for troubleshooting Offline Address Book (OAB) generation issues on the Microsoft Exchange Server, and OAB download problems on the Microsoft Outlook client. OABINTEG uses non-intrusive methods to gather information regarding the following objects: Active Directory Address List, Offline Address Lists and Address List related properties System Folders OAB Messages OAB Attachments Address List Hierarchy Address Book Recipients and data The tool simulates the following: The process a Microsoft Outlook client uses to connect to a public information store to download the OAB files. The method the OABGEN process uses to connect to the public information store to perform a rebuild of the OAB. For more information on the rebuild process, please see the “More Information on the OABGen Process” section later in this document. OABINTEG Tests OABInteg performs the following tests: (Blue – Active Directory Tests & Green – Mapi Tests) Test # Test Name Description 1 storealtest Validate if the information stores point to an address list 2 altest List all address lists in the organization 3 oaltest List all offline address lists in the organization 4 abrtest List the address book roots 5 proxytest Scan for users that will be skipped during the OABGEN process 6 rdntest Scan for all legacyExchangeDN's that have a final RDN greater than 64 characters 7 templatetest Scans the active directory for orphaned display templates 8 oabfldcheck Logon to the public information store and check the OAB system folders, messages and attachments 9 getabinfo_v2 Displays all of the address book entries from a profile and prints them out with the OAB Version 2 details. 10 getabinfo_v3 Displays all of the address book entries from a profile and prints them out with the OAB Version 3a details. 11 hierarchytest Displays the Offline Address List hierarchy from the selected public folder information store. Displays all folders and EntryID’s for all folders objects under the Offline Address List folder. 12 getoabseqnum Retrieve all MAPI profiles and read the last known downloaded OAB sequence number. 13 scanmapisvc Will scan the mapisvc.inf file for invalid attributes that can cause OAB Generation to fail. 14 alltests Performs all the LDAP tests against the active directory | [storealtest] [altest] [oaltest] [abrtest] [proxytest] [templatetest] WARNING: If you are going to run any of the MAPI tests (listed above in green) you must be using an Outlook client profile that is NOT in cached mode. When in cached mode we will use the local OAB files instead of the RFR service or ABP for lookups. This can cause errors to be thrown when running the tool. Additional Functionality OABINTEG will automatically create a profile called OABInteg-Admin-[TimeStamp] in HKEY_CURRENT_USER\Software\Microsoft\Windows NT\CurrentVersion\Windows Messaging Subsystem\Profiles, and will delete the profile when the tool has completed successfully. This is useful when there are no existing profiles on the machine. Display Functionality OABINTEG reports the status of the following in the display output: Online or offline status of the information store. EntryID used by the profile to open the OAB system folders. Replica server for the system folders. GUID of the OAB Container. OAB attachment number. Create date/time stamp of OAB messages and attachments. OAB System Folder Hierarchy List and EntryID’s for each folder. Display Counters OABINTEG reports the following counters in the display output: MAPI Test Related Message Class Normal found Message Class Differential found Message Class Unknown found Message Attachments found: Messages found but unable to read the properties System folders found Highest sequence number found Lowest sequence number found Biggest attachment found (in Bytes, MB & GB) Smallest attachment found (in Bytes, MB & GB) Biggest message found (in Bytes, MB & GB) Smallest message found (in Bytes, MB & GB) Total number of entries processed in the address book Active Directory Test Related Total information store address lists found Total address lists found Total offline address lists found Total AddressBookRoots objects found Total orphaned templates found in the Lost and Found container Total contacts found Total user mailboxes found Total groups found Total user objects that match primary proxy and mail attribute Total user objects that do not match primary proxy and mail attributes Total user objects that are missing one or both attributes Total user objects with valid legacyExchangeDN attribute Total user objects with invalid legacyExchangeDN attribute Total objects that have temp legacyExchangeDn’s Total objects that have RDN's that ok Total objects that have RDN's that are greater than 64 characters OABINTEG Command-Line Parameters The OABINTEG tool has the following parameters: Usage: OABInteg.exe [/s:servername] [/t:testname] [/l] (enable file logging) [/v: 1 or 2] (enable verbose logging) | Optional Commands [/d:SearchDN] [/p:# - Page Size] [U/:UserName] [/P:password] [/l] Logging output will go to c:\OABInteg.txt [/v:] Logging output will go to the screen. - Default logging is general - nothing selected | /v:1 for minimum and /v:2 for maximum logging. [/p:] Active Directory search page size. Default size is 64 and maximum is 512. [/dn:] -proxytest only!! NOTE: If you do not specify a search /dn: we will use base query of DC= OrgName,DC =local [/U:] Username. If you are going to connect use different credentials or connect to a different domain. [/P:] Password. If you are going to connect use different credentials or connect to a different domain. [storealtest] - Validate if the information stores point to an Address list. [altest] - Finds all address lists in the organization. [oaltest] - Finds all offline address lists in the organization. [abrtest] - Finds the address book roots properties. [proxytest] - Scan for users that will be skipped during the oabgen process. [rdntest] - Scan for all legacyExchangeDN's that have a final RDN greater than 64 characters. [templatetest] - Scans the active directory for any orphaned display templates. [oabfldcheck] - Logon to the public information store and check the OAB system folders, messages and attachments [getabinfo_v2] - Open the default address book for a selected profile and dump all entries using OAB V2 props. [getabinfo_v3] - Open the default address book for a selected profile and dump all entries using OAB V3a props. [getoabseqnum] - Retrieve all MAPI profiles on a client and read the last known downloaded OAB sequence number. [scanmapisvc] – Scan the mapisvc.inf file for invalid entries that can cause OAB Generation to fail. [hierarchylist] - Gets and displays the DEFAULT OAB FOLDER hierarchy information. Will display all folders and the EntryID for all folders under the default oab folder. [alltests] - Runs all the LDAP tests | [storealtest][altest][oaltest][abrtest][proxytest][rdntest][templatetest]. NOTE: The LDAP tests ([storealtest] [altest] [oaltest] [abrtest] [proxytest] [rdntest] [templatetest]) can only be performed against a global catalog server. NOTE: All AD queries are performed on port 3268. If no SearchDN is specified, the default Domain Naming Context container (DC= OrgName,DC =local) is used. Example 1: A typical active directory query uses syntax similar to the following: oabinteg.exe /s:GCName /t:TestName /d:OU=Managers,DC= OrgName,DC =local Example 2: To perform a MAPI test from an Exchange Server or Outlook client, run the following syntax: oabinteg.exe /s:ExchangeServerName /t:oabfldcheck Test Details TEST - [storealtest]- Validate Store Offline Address List Each Microsoft exchange server has a default offline address list associated with it. If this setting is not properly set, it can cause problems when trying to query the exchange system folders. This test will check all of the exchange information stores to see if they have this setting applied. TEST- [altest]- Address Lists Test This test will query the CN=Microsoft Exchange active directory object, and extract all of the address lists in the exchange organization. This is useful in determining if there are inconsistencies between active directory domain controllers. TEST - [oaltest] - Offline Address List Test This test will query the CN=Microsoft Exchange active directory object, and extract all of the offline address lists in the exchange organization. TEST - [abrtest]- Address Book Roots Test Microsoft Exchange configures trees of address book containers to show up in the MAPI address book. This attribute on the Exchange Configuration object lists the roots of the address book container trees. During certain situations (hosting) the entries to the addressBookroots can become mis-configured thus causing problems with rebuilding address lists. This test will pull all of the attributes from the addressBookroots object so they can be compared to the address lists in the organization. TEST - [proxytest] - Simple Mail Transfer Protocol Address Mismatches and legacyExchangeDN Mismatch Prior to Service Pack 1 for Exchange Server 2003, company-wide full downloads of the OAB could occur because of Simple Mail Transfer Protocol (SMTP) address mismatches. In an SMTP address problem, a differential update is created, but Outlook cannot correctly parse the update. All mail-enabled objects (mailbox, contact, and distribution group) in your organization must have a mail attribute and a proxyAddresses attribute. The proxyAddresses attribute must contain a primary SMTP proxy with the same alias as the mail attribute. For example, if the mail attribute is someone@contoso.com, SMTP:someone@contoso.com must reside in the proxyAddresses attribute. A valid primary SMTP proxy must be in the form "SMTP:@" (not "smtp:"), where alias is the user's e-mail alias and domain.com is the company's domain name. Note: A primary SMTP proxy starts with "SMTP:" (all uppercase) and additional SMTP proxies start with "smtp:" (all lowercase). Other factors to consider with respect to SMTP addresses include: The maximum length of an SMTP relative distinguished name (the portion followed by the at sign (@)) is 63 characters. The alias and the domain name must not begin with any of these characters: space, !"#$%&`()*+,-./ or any unprintable character. Domain names typically begin with a letter or number, but mistyping a space at the beginning is a common error. The SMTP problem as it relates to OAB downloads affects differential updates only. The user's Active Directory directory service entry must be changed to appear in the differential update file. It is possible for the entry to appear in the differential update (as if a change had been made) if there exists another user in your organization who has the same displayName attribute in Active Directory. In Exchange Server 2003 SP1, SMTP address mismatches no longer create the need for full OAB downloads because the users with the mismatched addresses are not added to the OAB. Instead, when such a user is encountered, the following event is generated in the Application event log of the OAB server: Event Source: MSExchangeSA Event ID: 9325 Event Type: Error Description: OALGen will skip user entry %1 in address list %2 because the SMTP address %3 is invalid. To determine whether to add a user to an OAB, OABGen performs several validation tasks to determine if the SMTP proxy addresses for each user are correct and not malformed or mismatched. If any of the validation tasks fail, the user is not added to the OAB, and the earlier event log entry is logged. This will also stand for the legacyExchangeDN attribute. If this attribute does not begin with /=o or /=O we can not verify if this is a valid object and we will skip this user object during the rebuild process. We will test to see if the objects legacy exchangeDN starts with /o= or /O=. This test will scan for all user objects to see if they have the correct attributes (mail and primaryproxy), if not they will be logged by this application. TEST - [ templatetest]- OAB Orphaned Display Templates Test Detail Template files allow you to see details on mailboxes, custom recipients, or distribution lists. For any reason if the display templates are removed from and you try to generate the default offline address list or any other address list that has been created the offline address list may not be generated on the Exchange server. Event ID 9126 will be logged in the Application event log. This test will search for orphaned display templates in the Lost and Found container in the AD so that they can be identified and removed. TEST- [rdntest] - RDN Size Check Tests In Exchange Server 5.5, the schema would never let an RDN exceed 64 characters. In Active Directory, the legacyExchangeDN is stored as a free-form string and there is no enforced limit. RDNs greater than 64 characters can cause changes in the way the OAB diff files get applied to a Microsoft Outlook client. In turn, this can cause Outlook to initiate a full OAB download. TEST- [getabinfo_v2] – Get Offline Address List with OAB Version 2 Properties This test will allow you to pull the default address list from a profile and download all of the address list entries. All of the entries that are retrieved and displayed with be with the OAB Version 2 properties. TEST- [getabinfo_v3] – Get Offline Address List with OAB Version 3a Properties This test will allow you to pull the default address list from a profile and download all of the address list entries. All of the entries that are retrieved and displayed with be with the OAB Version 3a properties. TEST- [hierarchytest] – Display Public Information Store Offline Address List Hierarchy This test will connect to the exchange servers public folder information store and get the hierarch list and folder properties from each child folder in the list. The properties that are returned are as follows: PR_DISPLAY_NAME_W PR_REPLICA_SERVER_W PR_URL_NAME_W PR_ENTRYID TEST- [getoabseqnum] – Display the oab sequence number from all the profile on a system This test will open the profiles table on a computer and scan for all of the profiles and extract the last downloaded oab file. This will contain the more recent oab sequence number. TEST- [scanmapisvc] – Scans the MAPISVC.INF file for invalid entries This test must be ran on the local system that you want scanned. This will scan the mapisvc.inf file for invalid entries that can cause profile generation problems. Invalid entries can lead to OAB generation problems. TEST - [oabfldcheck] - OAB System Folder Check Test NOTE: [oabfldcheck] MUST be run on a Microsoft Exchange Server or a workstation with the Microsoft Outlook client installed. Test 8-1: Checks to see if the following registry value is present. If it is, you will be given the option to remove this key: HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Exchange\\Exchange Provider registry key. Test 8-2: Checks to see if the following registry value is present. If it is, you will be given the option to remove this key: HKEY_CURRENT_USER\\SOFTWARE\\Microsoft\\Exchange\\Exchange Provider registry key. NOTE: With this key present, the OABGen process can fail and this is not a recommended configuration. Test 8-3: Checks to see if the following registry keys and values are present. Exchange 2003 SP2 OAB Generation Registry Keys HKLM\\SYSTEM\\CurrentControlSet\\Services\\MSExchangeSA\\Parameters registry key. Checks for OAL NT5 DN Rejection registry value. DS Access Keys HKLM\\SYSTEM\\CurrentControlSet\\Services\\MSExchangeDSAccess\\Profiles\\Default registry key. Checks for LDAPConnections registry value. Checks for AsyncLDAPConnections registry value. HKLM\\SYSTEM\\CurrentControlSet\\Services\\MSExchangeDSAccess\\Profiles\\Default\\UserDC1 registry key. Checks for Hostname registry value. Checks for PortNumber registry value. Checks for IsGC registry value. HKLM\\SYSTEM\\CurrentControlSet\\Services\\MSExchangeDSAccess\\Profiles\\Default\\UserGC1. Checks for Hostname registry value. Checks for PortNumber registry value. Checks for IsGC registry value. Test 8-4: Checks Windows Messaging Subsystem for user and Exchange Server MAPI profiles. Test 8-5: Creates an OABInteg-Admin profile, which is deleted when OABINTEG completes successfully. Test 8-6: Calls MAPILogonEx to obtain a MAPI Session. Test 8-7: Select a profile and logon using our session. Test 8-8: Checks the Sort Locale on the local machine. Test 8-9: Checks the Code Page on the local machine. Test 8-10: Call QueryIdentity and get the following information: Profile linked to Mailbox: Profile Version: Profile Type: Test 8-11: Call OpenAddressBook and Open the MAPI integrated address book . Test 8-12: Checks to see if we can pull the server that we are trying to connect to for NSPI queries. Test 8-13: Reads the Information Store table. Test 8-14: Checks the Hierarchy Server and determines if the information store is online or offline. Test 8-15: Grabs the PR_ADDRBOOK_FOR_LOCAL_SITE_ENTRYID attribute for the OAB system folders. Test 8-16: Opens the OAB system folder inside the public information store using the value specified by PR_ADDRBOOK_FOR_LOCAL_SITE_ENTRYID. Test 8-17: Search this folder’s hierarchy table for subfolders. Typically, these would be "OAB Version 2", "OAB Version 3a” and "OAB Version 4”. Test 8-18: Open the first folder that meets the above criteria. Also displays the following properties for the folder: PR_DISPLAY_NAME_W, PR_REPLICA_SERVER_W, PR_URL_NAME_W, PR_SUBFOLDERS, PR_FOLDER_CHILD_COUNT, PR_FOLDER_TYPE, PR_PUBLISH_IN_ADDRESS_BOOK, PR_HAS_RULES, PR_OVERALL_AGE_LIMIT Test 8-19: Displays the following properties for each message in the folder: PR_CONVERSATION_TOPIC_W PR_OAB_NAME_W PR_OAB_DN_W PR_OAB_MESSAGE_CLASS PR_MESSAGE_CODEPAGE PR_MESSAGE_SIZE PR_LOCALE_ID PR_OAB_SEQUENCE PR_OAB_CONTAINER_GUID_W PR_HASATTACH PR_CREATION_TIME Test 8-20: List the following properties for every attachment in each message: PR_ATTACH_NUM PR_DISPLAY_NAME_W PR_ATTACH_FILENAME_W PR_ATTACH_SIZE Test 8-21: Display the following counters: Message Class Normal found: Message Class Differential found: Message Class Unknown found: Message Attachments found: Messages found but unable to read the properties: System folders found: Highest sequence number found: Lowest sequence number found: Biggest attachment found: Smallest attachment found: Biggest message found: Smallest message found: Test 8-22: Delete the OABInteg-Admin profile. Test 8-23: Log off the profile. Test 8-24: Close the MAPI Session. Test 8-25: Un-initialize MAPI Subsystem. Test 8-26: Terminate the application. TEST - [alltests] - Runs all the LDAP tests This test will run all of the following tests in succession: [storealtest][altest][oaltest][abrtest][proxytest][rdntest][templatetest].