Run synchronization for Code42 User Directory Sync

Overview

After the Code42 User Directory Sync is configured, synchronize your directory service with your Code42 environment. Synchronization automatically creates users, updates their organization and role assignments, and deactivates users in your Code42 environment based on changes made within your directory service.

This article explains how to run synchronization, provides details about the available synchronization options, and describes how to troubleshoot synchronization errors.

Considerations

To perform synchronization, you must be authorized to access and manage the directory service used at your company (for example, Active Directory).
If you need help with Code42 User Directory Sync, contact your Customer Success Manager (CSM) to engage the Professional Services team.

Before you begin

Before you perform synchronization, you must do the following:

Install the Code42 User Directory Sync tool to a dedicated host computer or virtual machine.
Configure scripts to control how synchronization provisions users from your directory service to your Code42 environment.
Configure properties in the config.properties file to control how synchronization processing occurs.

Perform a synchronization

To perform a synchronization, run the C42UserDirectorySync executable either manually or in a scheduler. After synchronization, review logs in the \logs directory and view the provisioning changes in the sync log.

Manually

Open a command prompt on the host computer in which Code42 User Directory Sync tool is installed.
Navigate to the \bin folder of the Code42 User Directory Sync tool.
Run the C42UserDirectorySync executable to synchronize your directory service to your Code42 environment.
For example:
- Run the following command to synchronize the changes made since the last time synchronization was run:
  C42UserDirectorySync --sync-now
- Run the following command to perform a full synchronization:
  C42UserDirectorySync --sync-now --full-sync
Review logs in the \logs directory, and view the provisioning changes in the sync log.

Run the C42UserDirectorySync executable with additional options to perform dry-run synchronization, specify parameters, and to troubleshoot problems. See C42UserDirectorySync options below for descriptions of all the options you can run with the executable.

Scheduled

To schedule the sync to run on a repetitive basis, use a scheduler. When configuring a scheduler on a Windows host, ensure the task is scheduled to run as the same user who set the LDAP and SCIM passwords.

Use a scheduler such as:

the Windows Task Scheduler
a cron job
Third-party scheduling tools

C42UserDirectorySync options

Following are options that can be used with the C42UserDirectorySync executable.

To see all available options, run C42UserDirectorySync--help from the \bin folder in which the Code42 User Directory Sync tool is installed.

Options	Description
(none)	Executes the synchronization in dry-run mode. This performs a connection check between your directory service (LDAP server) and the Code42 authority server. It then queries for users that have changed since the last successful synchronization and outputs the username, active status, organization, and roles that would be provisioned to Code42 during a live incremental synchronization (using the `--sync-now` option).
`--auto-detect-ldap-server <DNS>`	Attempts to auto-detect an LDAP server using the provided DNS domain (for example: corp.code42.com).
`--changed-since <date>`	Synchronizes all users that haven't been updated since the specified date. Specify the date using an ISO format for the day (yyyy-MM-dd), and optionally, time (yyyy-MM-ddTHH:mm:ssUTC). When specifying the time, the time zone is optional and reverts to the local time zone if omitted. To ensure that you synchronize all users who have not been synced yet, either set a date far enough in the past to pick up all users who have not been synchronized, or first run `--sync-now` to synchronize the changes since the last time synchronization was run using the `--sync-now` option. This option cannot be run with the `--full-sync` option.
`--config <filename>`	Performs a synchronization using the specified configuration file. Without this parameter, the `C42UserDirectorySync` executable uses the config.properties file in the location in which the the Code42 User Directory Sync tool is installed.
`--debug`	Executes the command in verbose mode. This mode outputs network results and user details, as well as additional logging detail for each processing step.
`--files <filename>`	Performs a synchronization using a file containing a list of the users you want to synchronize (for example, users.txt). If you use this option, ensure you set the `driver.files.attribute.name` property in the config.properties file to define the proper attribute to use to look up users when searching LDAP (`sAMAccountName` by default). This option cannot be run with the `--filter` option.
`--filter <filename>`	Performs a synchronization using an LDAP search filter file that contains the LDAP query to use in place of the default (for example, filters.txt). Use query language specific to your directory service, for example: `'(&(objectClass=person)(mail=?))'` For more examples of filters that can be used with Active Directory implementations, see Microsoft's TechNet article. This option cannot be run with the `--files` option.
`--full-sync`	Performs a full synchronization from your directory service to your Code42 environment: Dry-run mode When run alone, `--full-sync` executes the synchronization in dry-run mode. This mode performs a connection check between the LDAP server and the Code42 authority server. It then queries for all users in the search base or filter file and outputs the username, active status, organizations, and roles that would be provisioned to Code42 during a live full synchronization. Full synchronization When run with the `--sync-now` option, this option performs a live full synchronization, for example: `C42UserDirectorySync --sync-now --full-sync` (This differs from running a synchronization with the `--sync-now` option by itself, which only includes incremental changes made since the last synchronization.) Resulting provisioning changes are shown in the sync log. The following options can be used with `--full-sync` : `--config <filename>` `--debug` `--files <filename>` `--filter <filename>` `--sync-now` `--trace`
`--ldap-bind-password`	Reconfigures the LDAP password in the event the password is updated for your LDAP directory service use. Running this option writes the encrypted version of the LDAP password to the config.properties file, and verifies the password against the LDAP service. If errors are reported, address the errors before proceeding.
`--scim-password`	Reconfigures the SCIM password in the event the password is regenerated for the Code42 User Directory Sync in the Code42 console. Running this option writes the encrypted version of the SCIM password to the config.properties file, and the network connection is tested between the LDAP server and the Code42 authority server. If errors are reported, address the errors before proceeding.
`--sync-now`	Performs a synchronization from your directory service to your Code42 environment: Incremental synchronization When run alone, `--sync-now` synchronizes the changes since the last time synchronization was run using the `--sync-now` option. Resulting provisioning changes are shown in the sync log. Full synchronization When run with the `--full-sync` option, this option performs a live full synchronization, for example: `C42UserDirectorySync --sync-now --full-sync` (This differs from running a synchronization with the `--sync-now` option by itself, which only includes incremental changes made since the last synchronization.) Resulting provisioning changes are shown in the sync log. The following options can be used with `--sync-now`: `--changed-since <date>` `--config <filename>` `--debug` `--files <filename>` `--filter <filename>` `--full-sync` `--trace`
`--trace`	Executes the synchronization in dry-run mode which includes all logging information. This option should be used for generating more verbose logging than provided by `--debug`. Use only for debugging complicated configuration or runtime problems.
`--use-insecure-ldap`	Uses an insecure LDAP connection when communicating with an auto-detected LDAP server.
`--version`	Shows the Code42 User Directory Sync version and exits.

Troubleshoot synchronization

See the following guidance to troubleshoot common issues when running synchronization for Code42 User Directory Sync. To view synchronization logs, see the \logs directory in the location in which the Code42 User Directory Sync tool is installed.

Exit codes

Following are exit codes that occur when a synchronization process 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.

Error messages

Following are some of the most common error messages that appear in logs.

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 of users in Code42 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 that 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 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.
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.

External resources

Microsoft: Active Directory: LDAP Syntax Filters