Troubleshooting Standard AD Sync Issues (Troubleshooting)

“HELP! I’m a PaperCut system administrator and I’m having issues with our user/group sync from Active Directory! How can I fix it?”

Importing users & groups from Active Directory is the most popular and widely-used method of managing users in PaperCut NG/MF. It’s a highly efficient and reliable service, which provides the flexibility to administer a wide range of environments.

However like most things in life, problems can and do arise, and in this article we will address how you can resolve the most common synchronization issues with Active Directory.

NOTE: It’s important to mention that this article only covers troubleshooting the standard connection to Active Directory. We discuss troubleshooting LDAP synchronization and synchronization from other directory sources in the manual and in other articles.

The Basics

In this article we discuss some basic checks on configuration that can affect the success of your user/group synchronization with PaperCut, as well as specific issues and errors that you may encounter with your sync.

Our article here details a few potential limitations with AD. We recommend taking a look over that article to make sure that the sync issue you are experiencing isn’t related to any of those limitations.

Here are some basic troubleshooting checks you can perform to help rule out the possibility that the problem isn’t the result of your current configuration:

1. A common cause of sync problems is changes in your environment - such as on the network, domain, permissions, etc. Check your change-control records, and discuss with your team, to see whether this applies in your case.

2. Because PaperCut NG/MF’s user list is essentially a mirror of the directory source that you point it to, your sync will only find what you ask it to find. The User/Group Sync page (found on the PaperCut admin web interface, in Options → User/Group Sync) provides the option to either ‘Import all users’ or ‘Import users from selected Groups’ - so make sure that this option is set correctly for your requirements. If you are using the ‘sync users from selected groups’ option, take a careful look through the list to ensure that the relevant groups containing your PaperCut users are included.

3. PaperCut NG/MF has a simple way to test the sync source connection. In the PaperCut admin web interface navigate to Options, then click on the User/Group Sync tab.

Scroll down to Test Settings.

Watch the pop-up window for any error messages, like the example below.

4. By default PaperCut NG/MF runs as the local SYSTEM service account. Generally this is adequate to facilitate a successful read-only sync with AD to obtain the relevant user and group attributes and OU profiles from Active Directory.

However, in some instances (e.g. if the Active Directory server has restricted access or is a member of a different domain) then the local SYSTEM account may lack adequate permissions, in which case a service account with adequate read privileges to Active Directory is required in order for the sync to succeed.

If you need to change the PaperCut’s service account, review our article here for guidance on achieving this.

5. The server on which PaperCut NG/MF is installed requires a connection to a valid Domain Controller (DC). PaperCut uses that connection to provide the sync process.

To confirm an AD connection for the server, open command-prompt on the server and type:

echo %logonserver%

A valid response will be the Domain Controller that the PaperCut Server is connected to.

I’ve covered “The Basics” but I’m still having issues!

Ok, so you checked the items above but these suggestions didn’t help to fix your issue. No problem, we’ll now focus on a few specific scenarios that can occur.

My sync fails to run successfully

When PaperCut syncs with Active Directory, it relies on a separate executable called UserDirAd.exe. You need to ensure that this directory is included in your Anti-Virus exceptions.

When troubleshooting sync issues, we recommend following this knowledge base article which details how to obtain debug output from AD to help determine the exact reason for the failure.

I see an “error creating user” message in the sync status popup

Starting User synchronization…
Synchronizing users and groups
Synchronization process starting
Retrieving users (may take a while on large networks)…
Retrieving existing users from database…
Checking for new users to add…
ERROR creating user bobsmith in the application database. Could not execute JDBC batch update; SQL

Typically this error indicates an issue writing to the PaperCut NG/MF database. We recommend restoring the database from your most recent backup in order to resolve this user sync issue.

I see an “error creating new users” in the Application Log

This is a very generic error message that doesn’t provide specific details of the problem, so we need to gather more information. We recommend using the Test Settings button on the sync page or performing the AD debug steps in order to help isolate the cause of these errors.

A particular user/group is failing to sync

In order to keep the sync process compatible with older Windows environments, PaperCut NG/MF relies on the pre-Windows 2000 variant of usernames, known as the sAMAccountName which imposes a strict 20 character limit. You can see an example in this knowledge base article which clarifies where to find it within a user’s Active Directory Properties panel.
If you have a large number of AD groups and previously configured a group override (as mentioned here), check the PaperCut NG/MF config editor to see if there is still a group filter or list override in place.

You can find the config editor by opening the PaperCut admin web interface, and going to the Options → Actions → Config editor (advanced) page.

The relevant keys are:

User-source.ad.group-ou-filter
User-source.group-list-override

If it’s a user that is missing, you might have ignored users set, in which case search config editor for these keys:

User-source.ignored-users
User-source.ignored-users.x

Also it would be worth checking whether the missing user object is disabled in Active Directory. By default, PaperCut NG/MF does not synchronize users with a ‘disabled’ status in the directory source, so this needs to be manually enabled if you want these users included in the sync (see “Import disabled users’ checkbox at the top of the User/Group Sync settings, or following this article here).

User details are not updating via the sync

The first thing to check in this scenario is that the following checkbox is enabled on the User/Group Sync page:

This ensures that all details relating to email addresses, departments, card/id numbers, etc, are imported from the directory source.

Once you select that option, you can either leave the sync to run again overnight, or you can press Synchronize Now to immediately test the results of using this option for your sync.

NOTE - If you would like to synchronize a secondary email address for your users, you can follow the instructions https://www.papercut.com/kb/Main/SyncingFromASecondaryEmailAddressInActiveDirectory.

If you are still experiencing an issue with the retrieval of some details for your users, we recommend that you run the AD debug tool to help establish the cause.

If necessary, you may need to change the service account that is running your PaperCut Application Server service. The details of this step are detailed here.

Group membership is not updating via the sync

If you completed the standard troubleshooting steps above regarding user and group sync, and there is still a specific issue with regards to your user’s group membership not updating via the sync, then it’s worth mentioning a common issue with Active Directory, and applications that use its API to import users. The API cannot grab the user objects based on group membership if the group that PaperCut NG/MF is pointing to is the user’s “Primary Group”. Take a look at this article here which provides further details.

Link to original article