Run synchronization for Incydr User Directory Sync

Overview

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

This article explains how to run synchronization and provides details about the available synchronization options. For help troubleshooting synchronizations, see Troubleshoot Incydr User Directory Sync.

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 Incydr 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 Incydr 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 Incydr 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

Before you run synchronization, perform a test synchronization in dry-run mode.

After you have successfully tested synchronization with dry-run tests, perform the actual synchronization:

Open a command prompt on the host computer in which Incydr User Directory Sync tool is installed.
Navigate to the \bin folder of the Incydr User Directory Sync tool.
Run the C42UserDirectorySync executable to synchronize your directory service to your Incydr 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 Incydr 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 Incydr cloud. 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 Incydr 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 Incydr 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 Incydr 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 Incydr cloud. 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 Incydr 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 Incydr User Directory Sync in the Incydr 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 Incydr cloud. If errors are reported, address the errors before proceeding.
`--sync-now`	Performs a synchronization from your directory service to your Incydr 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 Incydr User Directory Sync version and exits.

External resources

Microsoft: Active Directory: LDAP Syntax Filters

Search