Set up the directory agent

The agent runs as a Windows service on a member server of the domain. It does not belong on the domain controller itself.

Prerequisites

A Windows server joined to the domain. Outbound it needs to reach the domain controller over LDAPS on port 636 and Conbool over HTTPS on port 443. Nothing has to be opened inbound.

The account the service runs under needs read access to the directory. For the incremental sync in Active Directory two optional replication rights are added, see Active Directory.

Create a join key

Under Settings, Directory, Directory agent, add an agent and name it after the server it will run on. Conbool issues a join key for it.

The key carries the target address. The same installation package therefore works both for Conbool in the cloud and for an installation in a company data centre.

Install

The installation package is offered for download on the same page. The wizard asks for the join key and nothing else.

To do it by hand, the program provides subcommands:

conbool-agent preflight conbool-agent enroll --key cb1.… conbool-agent install

preflight checks the prerequisites and reports each point separately before anything is set up. enroll registers the agent with the join key. install creates the service with delayed autostart and a restart rule in case it ends unexpectedly. uninstall removes it again.

The service writes the result of every run to the event log, where a run can be followed with actual numbers.

Define the scope

The scope defines who the agent reads: the parts of the directory, an additional filter, how disabled accounts are treated, how shared mailboxes are recognised, and the attribute mapping.

After every change to the scope the agent first performs a dry run and writes nothing. The dry run shows how many people would be created, changed or removed. Only after approval does it write and delete again.

Interval and sync on demand

The interval defines how often the agent looks for changes. Once a day it additionally reconciles the complete set, regardless of the interval. The "Sync now" button hands the agent that instruction the next time it reports in, so nobody has to touch the server.

Deletion limit

If more than ten percent of the people would disappear in one run, the agent writes nothing and reports the run as held. A misplaced scope or a temporarily incomplete directory therefore cannot delete half the records. Once it is confirmed that those people really are gone, an approval releases the run.

Updates

The agent fetches new versions itself. Before replacing itself it starts the downloaded version once and verifies its version number, so an unusable package cannot replace a running service. The previous version stays alongside.

Revoking

A revoked agent can no longer sign in and needs a new join key. People already transferred stay untouched.

Several agents

Several agents per tenant are supported, for two domains or two sites. Each agent owns its own scope and does not clear the others. Entra ID and local Active Directory side by side is supported as well.