AD Connector in Action: Selective Sync Made Simple

Need to sync Active Directory (AD) with UCS, but only specific parts? The AD Connector lets you fine-tune exactly what gets synchronized.
The AD Connector keeps user accounts, groups, and computer objects in sync between AD and UCS’s OpenLDAP, along with any connected services. But here’s the thing: In large environments, you don’t always want to sync everything. Sometimes, it’s about choosing what matters most. Think of it like setting up a virtual tollgate—some data gets the green light, and the rest stays put.

Before UCS 5.0-9 (released in September 2024), your options for excluding areas were limited. Now, you’ve got more power. You can tell the AD Connector, “Sync this, but skip that.” The best part? The rules stick, even when your directory evolves. And you can get granular—sync a specific part of your directory but leave certain objects behind. For example, let’s say you want to sync only the high school students in a comprehensive school. Done. The other grade levels stay out of it.

This article walks you through everything: How to set up selective synchronization, how to exclude areas of your directory, how to filter specific objects, and why the command line is your best friend for tweaking settings. Ready to take control of your syncs? Let’s dive in!

Want the fastest way to get things running? Just set the LDAP filters using UCR variables—straight from the shell. Here’s how it works: First, use the ucr set command to adjust your settings. Then, restart the AD Connector with systemctl restart univention-ad-connector. Finally, check the logs to make sure everything’s working as it should. You’ll find the details in /var/log/univention/connector-ad.log and /var/log/univention/connector-ad-status.log.

Why not use the UMC? Sure, the Univention Management Console (UMC) is user-friendly, but let’s be honest—it’s not always the fastest option. You’ll spend time clicking through multiple menus just to set variables, test changes, and check logs. With the shell, it’s a different story. Everything happens in one clean, streamlined workflow. From configuration to troubleshooting, you can handle it all quickly and efficiently without breaking your rhythm.

Need more detailed guidance? Check out the Additional tools / Debugging connector problems section in our manual, where we walk you through identifying and fixing sync issues step by step.

Previously, the AD Connector relied on exclude lists to keep certain elements out of the sync. Entire trees or sub-branches could be excluded, which worked well at first—until you needed to skip specific branches or individual objects. Another issue? New trees or organizational units (OUs) were synced by default, sometimes unintentionally.

Now, you’re in charge. With allow and deny filters, you decide exactly what gets synced and what stays out. It’s easier, faster, and much cleaner. Instead of painstakingly excluding everything you don’t want (deny), you can simply focus on syncing what you do want (allow).

The AD Connector gives you plenty of ways to refine your sync settings:

• Select objects based on their location in the LDAP subtree.
• Choose objects that match specific LDAP filters.
• Or flip the logic: Sync everything except objects from a specific subtree or those matching a filter.

This setup works seamlessly for the core object types the AD Connector handles: user accounts, groups, and computers. Containers, however, are a bit different. They don’t hold data themselves—they’re more like folders that organize other objects. One special type of container is the Organizational Unit (OU), which acts as the base container for structuring your directory.

Here’s a real-world example: Let’s say you’re managing user accounts for multiple schools—School 1 through School 5. You only want to sync accounts from School 1. With allow lists, it’s simple: “Sync only School 1.” Everything else stays out. Now here’s where it gets interesting: If School 6 is added, you don’t need to lift a finger. With a deny-based approach, you’d have to go back and explicitly exclude School 6. But with allow filters, you’re already covered. Since only School 1 is allowed, School 6 is automatically left out.

Imagine your bridge has multiple toll gates, each with its own rules for who gets through and who gets stopped. To keep things running smoothly, there needs to be a clear order of operations. And let’s face it, real-world setups are rarely straightforward. Sometimes it’s about syncing entire schools, other times it’s just specific groups like teachers or students. It can get messy fast.

The AD Connector simplifies this with a well-defined priority system for selective sync rules. While the rules run in parallel, they’re processed in a fixed order to ensure everything stays organized and predictable:

1. allowsubtree: First, the connector checks if the object is part of an allowed subtree.
2. allowfilter: If no subtree matches, an LDAP filter determines whether the object is allowed.
3. ignoresubtree: Next, it checks if the object is part of an ignored subtree.
4. ignorefilter: Finally, an LDAP filter decides if the object should be ignored.

Here’s the key: As soon as a rule applies, the processing stops. If the object is ignored—thanks to either an ignored subtree or filter—it’s excluded from the sync. If the object is allowed, the connector moves to the next rule. If no further rules apply, the object gets synced.

The AD Connector connects two directory services: UCS LDAP and Active Directory. Data can flow in either direction—UCS to AD, AD to UCS, or even both at the same time. To keep this flow under control, the subtree rules (allowsubtree) come in two flavors: allowsubtree/.*/ucs and allowsubtree/.*/ad. In most setups, you’ll use both since synchronization typically runs both ways.

Filters, however, work a little differently. They’re always active, regardless of the sync direction. That said, you’ll need to define filters separately for each side if you want them to apply across the board.

Let’s break this down further with the four rule types and see how they manage the data flow.

By default, the AD Connector syncs everything—both ways. But with allowsubtree, you take full control by specifying exactly which LDAP subtrees should be synchronized. Anything outside those subtrees stays out.

For example, let’s say you only want to sync objects from School 1. Here’s how you’d configure it:

ucr set connector/ad/mapping/allowsubtree/school1/ucs="ou=school1,dc=ucs,domain"

In this case, the connector only syncs objects from that subtree (ou=school1)—nothing more. Other schools, like School 2, are ignored, even if new areas are added later. This works seamlessly in both directions:

• From UCS LDAP to Active Directory: use allowsubtree/.*/ucs.
• From Active Directory to UCS LDAP: set allowsubtree/.*/ad.

For example, to sync School 1 from AD into UCS LDAP, you’d run:

ucr set connector/ad/mapping/allowsubtree/school1/ad="ou=school1,dc=ad,domain"

While allowsubtree sets the overall framework by defining which broad areas to sync, filters give you precision. You can use them to include or exclude individual objects based on attributes or object classes. Let’s say you only want to sync objects where the description is set to “sync” and the object belongs to the “person” class. Here’s how you’d do it:

ucr set connector/ad/mapping/allowfilter/sync="(&(description=Sync)(objectClass=person))"

In the next section, we’ll dive deeper into how these filters work and how they help you fine-tune your synchronization.

Once you’ve set the broad rules with allowsubtree, it’s time to get specific with allowfilter. While allowsubtree opens the gate for an entire subtree, the filter acts like a customs officer, inspecting individual objects to decide what actually gets through. Think of it this way: The big gate (allowsubtree) lets in the whole section, but the filter (allowfilter) takes a closer look and only approves objects that meet your exact criteria.

Say you only want to sync users from School 1 who have the attribute description=sync. Here’s how you’d set that up:

ucr set connector/ad/mapping/user/allowfilter="(description=sync)"

Now, only users matching this attribute get synchronized. Everyone else? They stay put. The allowfilter works across all the main object types the AD Connector handles: user (user accounts), group (group objects), container (standard containers), ou (organizational units) und windowscomputer (computer objects).

Note: If an object that originally passed the filter gets updated and no longer meets the criteria, the AD Connector will stop syncing it. To fully disable the sync for that object, you’ll need to make changes on both sides—UCS LDAP and Active Directory.

Think of ignoresubtree as the counterpart to allowsubtree. Instead of granting access, it blocks specific LDAP subtrees from being synchronized. This is perfect for situations where you want to keep certain areas or objects out of the sync process.

Let’s say you don’t want to sync alumni—former employees or students. Using ignoresubtree, you can easily exclude that section from synchronization:

ucr set connector/ad/mapping/ignoresubtree/ignore1="cn=alumni,dc=ucs,domain"
ucr set connector/ad/mapping/ignoresubtree/ignore2="cn=alumni,dc=ad,domain"

With this configuration, anything under cn=alumni is completely ignored—in both UCS LDAP and Active Directory.

While ignoresubtree excludes entire sections of your directory, ignorefilter gives you even more precision. This rule allows you to skip specific objects based on an LDAP filter—no matter where they’re located in the directory tree.

Let’s say you want to ignore all users where the description is set to no sync. Here’s how you configure that:

ucr set connector/ad/mapping/user/ignorefilter="(description=no sync)"

The ignorefilter works with the same object types as allowfilter: user, group, container, ou, and windowscomputer.

But what if you need to exclude specific objects directly, without relying on filters? That’s where the ignorelist comes in—a topic we’ll dive into in the next section.

The ignorelist is a unique feature of the AD Connector. While it works similarly to ignorefilter, it’s simpler and a bit more limited. It’s designed for quick, targeted exclusions of specific objects, like individual users or groups.

Want to exclude the users Administrator and root from synchronization? Just add them to the ignorelist:

ucr set connector/ad/mapping/user/ignorelist="Administrator,root"

The ignorelist exists mainly for backward compatibility. Before filters were introduced, this was the go-to method for excluding objects. By keeping it around, updates won’t break existing configurations, and your legacy setups continue to work without any issues.

The AD Connector combines allow and deny rules to give you precise, firewall-like control over what gets synchronized. Sure, filters and rules might seem a bit complex at first, but that complexity is exactly what makes the connector so adaptable. No matter how unique your scenario is, these tools let you tailor the sync process to fit your needs perfectly.

The result? Less administrative overhead, fewer errors, and a rock-solid synchronization process that’s handled every challenge so far—no matter how tricky.

Got questions? Check out the “Selective synchronization” chapter in our manual, or join the discussion in our forum. We’d love to hear from you!