Skip to main content

Who is this article for?

Incydr
Code42 for Enterprise
CrashPlan for Enterprise

Incydr, yes.

CrashPlan for Enterprise, yes.

Code42 for Enterprise, yes.

CrashPlan for Small Business, no.

This article applies to Code42 cloud environments.

HOME
GETTING STARTED
RELEASE NOTES
FAQs
APIs
SYSTEM STATUS
Code42 Support

Troubleshoot Code42 User Directory Sync

Overview

This article provides suggestions for troubleshooting problems with Code42 User Directory Sync. 

Use the Code42 app in Azure AD for provisioning
If you use Active Directory as your directory service, we recommend you use the Code42 app in Azure AD to provision users to Code42 instead of Code42 User Directory Sync. For more information, see How to provision users to Code42 from Azure AD.

Considerations

  • If you need help with Code42 User Directory Sync, contact our Customer Champions for support, or contact your Customer Success Manager (CSM) to engage the Professional Services team.
  • To perform troubleshooting as described in this article, you must be authorized to access and manage the directory service used at your company (for example, Active Directory).

Before you begin

  • Double-check that you have correctly:
  • Carefully review log files in the \logs directory where the Code42 User Directory Sync tool is installed.

Troubleshooting checklists

Use the following checklists to help you troubleshoot problems with Code42 User Directory Sync.

Setup and configuration

If you are having problems setting up Code42 User Directory Sync for the first time, or suspect the problems are configuration-related, use the checklist below to help you troubleshoot them. 

For configuration instructions, see Configure Code42 User Directory Sync.

Use a supported version of Microsoft Active Directory

Code42 User Directory Sync is supported for use only with Microsoft Active Directory versions 2003 through 2019.

Make sure you deploy to a dedicated server

Make sure that the host server where the Code42 User Directory Sync tool is installed is a dedicated bare metal server or virtual machine. Other services running on the host could interfere with synchronization.

Ensure the ldap.baseurl property isn't pointed to a load balancer

When you installed the Code42 User Directory Sync tool, you should have entered the address of your directory service server to the ldap.baseurl property. The User Directory Sync tool uses LDAP paging for larger search results, so load balancers may cause a paged request to go to a different directory server, which isn't supported by Active Directory's paging implementation. To fix the problem, change the property's value in your configuration.properties file.  

Ensure the ldap.baseurl property uses the correct port

When you installed the Code42 User Directory Sync tool, you should have included a port number in the ldap.baseurl property along with the address of your directory service server, and the port needs a firewall rule to ensure access. If you did not include a port number, the port defaults to 389, or in the case of Secure LDAP, to port 636. If you have problems with port access, ensure your firewall rules are set correctly and set the correct port number in the ldap.baseurl property in your configuration.properties file

Ensure the LDAP bind username is in the correct format

When you installed the Code42 User Directory Sync tool, you entered the username of the authorized service account for your directory server to the ldap.bind.user configuration property. You must use the format of user@domain.com, domain\user, or "cn=user,dc=domain,dc=com" (the default value is "cn=read-only-admin"). If the username is not in a format that complies with your directory server settings, LDAP authorization may fail. We suggest configuring the user@domain.com format for service accounts in the config.properties file.

Synchronization

If you have problems running synchronization, use the checklist below to help you troubleshoot them.

For synchronization instructions, see Run synchronization for Code42 User Directory Sync.

Make sure that passwords are correct

When you installed the Code42 User Directory Sync tool, you may have been prompted to enter the LDAP bind user and the Code42 SCIM user passwords. You may have also updated these passwords by running the --ldap-bind-password or --scim-password flags in the command prompt.

These passwords are then encrypted and stored in the config.properties file under the ldap.bind.password property and the scim.password property, respectively. If passwords are not set using the command prompt, or are not the correct passwords for the LDAP or SCIM user, synchronization fails.

Following are some of the error messages that can occur if these passwords are not correct:

    • LDAP: Error Code 49*, data 52e*
    • LDAP Service, SCIM Service failed to start
    • A failure occurred with exit code 2
    • A failure occurred with exit code 3

The passwords can be incorrect for many reasons, for example:

  • You moved the Code42 User Directory Sync tool to a new host.
  • You changed to a new LDAP bind user or changed their password.
  • You regenerated the password for the SCIM user
  • You attempted to run User Directory Sync under a different user in Windows.

To fix incorrect passwords, reconfigure the passwords with the following commands:

  • LDAP bind password: C42UserDirectorySync --ldap-bind-password
  • SCIM password: C42UserDirectorySync.bat --scim-password

Passwords are encrypted in a specific manner

Code42 User Directory Sync encrypts passwords entered through the command prompt. The encrypted password is then stored in the config.properties file. The mechanism to encrypt these passwords is specific to the operating system:

  • Encryption is specific to the user in Windows
    To successfully decrypt the password, the account used at the command prompt to set the password must also be used when running Code42 User Directory Sync manually or as a scheduled task.
  • Encryption is specific to the machine in Linux
    If the Code42 User Directory Sync tool is transferred to a different host, the new host is not able to decrypt the stored password, and you must reset the password.

For more information, see our guidance on password management in Configure Code42 User Directory Sync.

Check the Sync Log to make sure users are provisioned as expected

When you run a synchronization with Code42 User Directory Sync, updates made to your Code42 environment from the provisioning are shown in the Sync Log. Check the log to ensure that users are provisioned as expected to Code42. The Sync Log shows the results from Code42 User Directory Sync as well as SCIM provisioning providers.  

The Sync Log is different from the files in the \logs directory where the Code42 User Directory Sync tool is installed. Files in the \logs directory record Code42 User Directory Sync processes. For errors and exit codes that can appear in the log files, see Logs below. 

Check that your LDAP bind user has the correct permissions

If the LDAP bind user defined by the ldap.bind.user configuration property doesn't have the correct permissions in your Active Directory server, the following issues may occur:

  • Large numbers of users aren't found by the Code42 User Directory Sync tool.
  • User attributes are missing.
  • Logs list this error for multiple users: last modified timestamp is null.

The LDAP bind user must have permissions in Active Directory to view the following components:

Check that the user running synchronization has the correct permissions

You can perform a synchronization either manually or with a scheduled service. In either case, there is a user who performs the synchronization, and that user must have the correct permissions to run the synchronization. If they don't, the synchronization fails with an Access is denied error message or other issues. 

The user running the synchronization must have the following permissions:

  • Manual or scheduled task: Permission to log in to the server hosting the Code42 User Directory Sync tool
  • Scheduled task: Permission to log on as a batch job to run the scheduled task

Run a full sync 

Typically when you run synchronization, you perform an incremental run that only looks for the changes made since the last synchronization. However, the incremental synchronization may have problems reconciling changes since the last run.

If you are having problems with an incremental synchronization, perform a refresh of the synchronization process by running a test full synchronization in dry-run mode:

C42UserDirectorySync --full-sync 

After resolving any problems uncovered by the dry-run test, run a full synchronization:

C42UserDirectorySync --sync-now --full-sync 

Ensure proper JavaScript syntax in the Active, Org, and Role scripts

When you set up Code42 User Directory Sync, you configured scripts to control how synchronization provisions users from your directory service to your Code42 environment. These scripts use JavaScript. Issues with these scripts are a very common source of synchronization problems. Carefully review your scripts to ensure that JavaScript errors aren't the root cause.

To help determine why your scripts don't work, back up the scripts and create new test scripts that point to a specific user and that contain the minimum processing desired. Then run synchronization in dry-run mode to try out the test scripts. If the test scripts run, add in other desired elements until you uncover possible scripting problems.

Don't attempt to provision users in nested groups by provisioning only the parent group

If you provision a parent group, users in that group are provisioned, but not the users in nested groups. To provision users in nested groups, you must include each nested group in your LDAP script search filtering.

Submit files to support

If you need help with Code42 User Directory Sync, contact our Customer Champions for support, or contact your Customer Success Manager (CSM) to engage the Professional Services team. Provide copies of the following:

  • The contents of the \logs folder from the location where the Code42 User Directory Sync tool is installed
  • Your Active, Org, and Role scripts
  • Your config.properties file
  • The c42db.mv.db database file from the directory where the User Directory Sync tool is installed

Logs

To view synchronization logs, see the \logs directory in the location where the Code42 User Directory Sync tool is installed.

The files in in the \logs directory record Code42 User Directory Sync processes, and are separate from the Sync Log, which shows the updates made to your Code42 environment from provisioning. 

Common error messages

Following are some of the most common error messages that can appear in logs when running synchronization.

Error message Cause Solution
Access is denied The user running the synchronization doesn't have the proper access rights to log files. Ensure that the service user is properly configured for read/write permissions in the directory where the Code42 User Directory Sync tool is installed.
Directory service did not return any users when checking for missing users. Skipping deactivation step.

There is a problem when checking for missing users in the directory service, and as a result, the deactivation in Code42 of users no longer visible in the directory is skipped.

Ensure that:

  • Filtering for missing users is set properly.
  • There are no network connection problems.
  • There are no permissions issues with the LDAP user.
Unique index or primary key violation

This error occurs during a synchronization following an upgrade from Code42 User Directory Sync version 1.1.0 or earlier. The cause is that a user's UID (sAMAccountName) in the LDAP directory was changed in the time between the last successful synchronization and the upgrade to the present version, causing the collision of two records for the same user with the same UID.

 

  • Solution 1
    Revert to the original backed up 1.1.0 or earlier version and run a --sync-now --full-sync  synchronization, then upgrade to the latest version of the Code42 User Directory Sync.
  • Solution 2 
    Delete the c42db.mv.db database file from the directory where the Code42 User Directory Sync tool is installed, then run a synchronization using the --sync-now --full-sync options to repopulate the database. Any users with UID changes between the last successful run and deleting the User Directory Sync database file need to be rectified in Code42.
LDAP: Error Code 49*, data 52e* The username and password are not accepted by the LDAP server. This may be due to the values being entered incorrectly, containing symbols, or the username not being readable (due to spaces or incorrect specification of the DN).

Configure the ldap.bind.user property in the config.properties file to be the FQDN of the LDAP service's user account. You may also need to include in the property the domain with the username, for example:
Domain\serviceAccount or username@domain.com.

 

If you still receive the error after attempting this solution, ensure the LDAP service account's password does not contain any of the following characters:/ \ ~ " ' |

LDAP Service, SCIM Service failed to start

Both the SCIM and LDAP services failed to start simultaneously. This occurs typically after an upgrade to a newer version of Code42 User Directory Sync.

 

This typically happens after an upgrade because:

  • Encryption is specific to the user/host on Windows. Therefore, new service accounts can't decrypt the password.
  • Encryption is specific to the host on Linux. Therefore, new servers can't decrypt the password.
Ensure that the SCIM and LDAP passwords are configured with the --scim-password and the --ldap-bind-password options, since the encryption is user-specific in Windows and machine-specific in Linux.

java.security.cert.CertificateException: No subject alternative DNS name matching

You do not have the hostname of the domain controller in your SSL certificate. Typically this error appears in the log at the initial synchronization.  

Update your internal certificate with the hostname of the domain controller in the SAN. 

 

If this is not possible, set synchronization to ignore this error by adding the --use-insecure-ldap option to the command line. However, use this option only for troubleshooting purposes. For secure processing, Code42 User Directory Sync requires that the hostname of the domain controller be in your certificate.

Unable to Access JAR file The Code42 User Directory Sync tool is installed in a directory with spaces in the file path. Upgrade to Code42 User Directory Sync version 1.3.0 or later.

Exit codes

Following are exit codes that occur when a synchronization terminates without completing.

Exit code

 

Error message

 

Cause

Solution

1 An error message specific to the validation failure is displayed. Invalid arguments Double-check that the arguments you used with the C42UserDirectorySync executable are entered and formatted properly.
2

A failure occurred with exit code 2.

 

 

There was an issue with the SCIM and LDAP URLs, usernames, or passwords. 

Verify usernames and the URLs are set in the config.properties file. Also ensure the passwords for the SCIM and LDAP users have been configured using the --scim-password and --ldap-bind-password options.

 

If you still encounter issues, run synchronization with the --debug option to get a more verbose log output to uncover possible network problems.

3

A failure occurred with exit code 3.

 

 

The Base DN is invalid or the passwords could not be decrypted properly.

Ensure the Base DN exists and is properly set in the ldap.baseDn property of the config.properties file. Also ensure the user running the synchronization (whether manually or through a scheduled task) is the same user that set the LDAP and SCIM passwords.

4

A failure occurred with exit code 4.

Invalid logic in the active, org, or role scripts.

Ensure the scripts are entered and formatted properly. 
  • Was this article helpful?