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
- Run the following command to synchronize the changes made since the last time synchronization was run:
- 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). |
|
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
This option cannot be run with the |
|
Performs a synchronization using the specified configuration file. Without this parameter, the |
--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. |
|
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 |
|
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:
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 |
--full-sync |
Performs a full synchronization from your directory service to your Code42 environment:
The following options can be used with
|
--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:
The following options can be used with
|
--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
If you still encounter issues, run synchronization with the |
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 |
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:
|
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 (
|
|
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:
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:
|
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 |
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