ADSync Tool Usage Guidelines

Overview

ADSync is a complex tool, and understanding its functionality is important to distinguish between expected behavior and malfunctioning scenarios.

There are certain actions which, as an Administrator, you should not take unless you fully understand and accept the consequences.

This document provides a comprehensive explanation of how ADSync works, equipping you with the knowledge to operate it effectively.

tip

Please make sure to read this document in its entirety before installing or starting the ADSync Service.

---

Installation

ADSync must be installed on ALL Active Directory Servers in the domain to ensure that all password changes are captured. Unlike other object changes, password changes are not always replicated between AD Servers.

Before installation, consider the following:

• Will this server monitor:
  • User Changes
  • Contact Changes
  • Group Changes
• Which AD Groups should be used for monitoring object changes?
• Do you need to configure a custom workflow or make changes to the ADSync.exe.config file?
• Are patches required post-installation?
• Can the Active Directory Server access the Atria API Web Service over HTTP or HTTPS?

The ADSync Service starts automatically upon installation. However, it will not start if it cannot connect to the API and validate the customer information configured in the config file. If the service fails to start, installation fails and rolls back any changes. Therefore, ensure API access and valid credentials before installing.

---

Customizations After Install

If custom workflows, patches, or config file changes are required immediately after installation, stop the ADSync Service immediately after installation completes.

Stopping ADSync can take time, especially if tasks are still in progress. The best approach is to kill the process.

warning

Killing the process is only acceptable immediately after installation. Doing so at any other time can cause queue corruption.

tip

Before completing the install, open Task Manager in the Processes tab so you can quickly kill the ADSync.exe process.

---

Startup

When ADSync starts, it may begin cataloging AD objects in scope. This process can be time-consuming if many objects are involved. This behavior is controlled by the EventLogWatch setting.

EventLogWatch

• True: Builds the catalog using the EventLog.
• False: Catalog is not built.

This setting enables ADSync to use EventLogs for detecting AD changes. It captures the specific nature of the change, such as:

• Type of object (new, changed, added/removed from a group)
• Specific properties that changed

This data informs ADSync of actions to take without needing to send API requests to Atria.

It works with these additional settings:

• UserAttributes, GroupAttributes, ContactAttributes
• UserAttributesSyncOnChange, GroupAttributesSyncOnChange, ContactAttributesSyncOnChange
• EventLogAddMemberEvents, EventLogRemoveMemberEvents, EventGroupAddMember, EventGroupRemoveMember

These help ADSync track relevant changes. It builds a catalog of in-scope items stored as .dat files in the Queue folder, maintained after startup.

If EventLogWatch is NOT set to True

ADSync relies on the LastUSN value in AD. It polls AD for objects with a higher LastUSN than the stored value, then:

• Submits API requests to check if the object was previously synced
• Submits another request to sync the object, even if the change is irrelevant

Setting EventLogWatch to True reduces load and improves performance, although it increases startup time.

---

Include and Exclude Groups

Exclude groups override include groups. If an object is not syncing, check for exclusion due to group membership.

info

Works like "Deny" in AD or the file system.

warning

Include and Exclude Groups must be Global Security Groups. ADSync may ignore members of other group types.

---

First-Time User Sync

When a user is first added to an "Include" group:

• The user syncs with a blank password
• Passwords sync only after a password change

note

Force users to change their password at next logon to ensure syncing.

---

Group Sync

Initial group GET requests:

• Determine if a group and its members were previously synced
• Block other sync activity until complete (can seem like a hang)

To avoid blocking, consider syncing large groups on a dedicated AD Server.

---

Log File

Logs are created under the ADSync\Logs folder daily (default 5MB).

tip

Consider moving logs to a separate drive or increasing their size.

Settings related to logging

Attribute	Description
maxFileSize	Max log size in bytes. Logging stops when limit is reached.
logFileCreationSchedule	Controls rotation: None, Daily, Weekly
customLocation	Path for log files (e.g., a separate disk)
reserveDiskSpace	Min disk space required to allow log growth

Logging Options

The LogMask setting controls exception details. It's a bitmask:

Name	Value
Message	1
Exception	2
Inner Exceptions	4
Error Code	8
Extended	16
Stack Trace	32768
Everything	65535

---

Filtering Options

The initializeData attribute in the FileLogTraceListener filter node controls logged detail:

Log Level	Description
Critical	Logs only critical events
Error	Logs critical and error events
Warning	Logs critical, error, and warning events
Information	Logs up to information events
Verbose	Logs everything including verbose events
ActivityTracing	Logs stop, start, suspend, transfer, and resume events
All	Logs all events

---

Operation

Stopping and Starting the ADSync Service

Stopping can take a long time if tasks are pending.

warning

Do not kill the process unless immediately after install. It can corrupt the queue.

If the queue is corrupt:

• Delete all files and folders in the ADSync\Queue folder except SyncActiveDirectory.config

info

Restarting the service rebuilds the catalog. This may take time.

Syncing Large Numbers of Items

Large syncs increase queue size, API, and SQL activity.

Use ThrottleUploads to limit items queued at once:

• Set ThrottleUploads = True
• Set ThrottleLimit = 50-100

This approach:

• Prevents excess API calls
• Ensures constant queue activity without overload
• Improves performance

Syncing Groups with Many Members

Syncing large groups requires ADSync to:

• Check sync status of all members via API
• Wait for API responses before continuing

warning

Do not restart or kill the service. Be patient.

info

Increase API timeouts to avoid failed requests.

Enable BatchUploads and set UploadBatchSize to process groups in chunks:

• Set BatchUploads = True
• Set UploadBatchSize = 50-100

This:

• Prevents timeouts
• Enables progress logging
• Improves visibility

---

Recommended Settings and Changes

Maximum Log File Size

Increase log size to 10MB:

<add name="FileLog" type="Microsoft.VisualBasic.Logging.FileLogTraceListener, Microsoft.VisualBasic, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" location="Custom" customLocation="...\\ADSync\\Logs" logFileCreationSchedule="Daily" traceOutputOptions="DateTime" autoFlush="True" maxFileSize="10000000">
  <filter type="System.Diagnostics.EventTypeFilter" initializeData="ActivityTracing,Information"/>
</add>

Create an Error Log

Create a log for warnings/errors:

<add name="FileLogErrors" type="Microsoft.VisualBasic.Logging.FileLogTraceListener, Microsoft.VisualBasic, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" location="Custom" customLocation="...\\ADSync\\ErrorLogs" logFileCreationSchedule="Daily" traceOutputOptions="DateTime" autoFlush="True" maxFileSize="10000000">
  <filter type="System.Diagnostics.EventTypeFilter" initializeData="Warning"/>
</add>

Update listener

<sources>
  <source name="DefaultSource" switchName="DefaultSwitch">
    <listeners>
      <remove name="Default"/>
      <add name="EventLog"/>
      <add name="FileLog"/>
      <add name="FileLogErrors"/>
    </listeners>
  </source>
</sources>

ApplicationSettings Table

Application Settings

Name	Value	Reason
UserPollTime	20	Reduces AD load
UploadPollTime	20	Reduces API and SQL load
LogMask	65535	Logs full error details
UploadMaxErrors	2	Limits retries
EventLogWatch	True	Improves efficiency via EventLog
UserAttributesSyncOnChange	True	Syncs only changed attributes
ContactAttributesSyncOnChange	True
GroupAttributesSyncOnChange	True
MaxGetStatusTries	5	Re-submits stuck objects
ThrottleUploads	True	Limits active queue size
ThrottleLimit	50-100	Optimal queue size
BatchUploads	True	Reduces size of group sync requests
UploadBatchSize	50	Optimal chunk size
MaxResubmits	2	Prevents endless retries

Increase API Timeout

Although APITimeout may be set to -1 (infinite), IIS has a default timeout of 110 seconds.

info

Syncing large groups may take 15+ minutes. Increase IIS timeout in the API's web.config:

<system.web>
  <httpRuntime executionTimeout="1800"/>
</system.web>

Set to 1800 seconds (30 minutes) or higher, like 10000, to prevent timeouts.

---

If you experience any issues or require any assistance, please contact us at support@getatria.com.