1 Introduction

Ldap Synchronization Connector, or LSC, is a tool for synchronizing data repositories, with a particular focus on identity information.

It can read from a variety of different sources, perform limitless transformations of data on-the-fly and write the results to a LDAP directory. The tool is designed to be fast, and extensible in all areas.

It is an open source project, released under the BSD license.

This document is a hands-on guide to all aspects of using LSC. This guide aims to be exhaustive. As such, the reader is not expected to read it from cover to cover, but is encouraged to skip to the sections he’s interested in. A quick-start guide is also available for the impatient.

2 Basic principles

2.1 Entries and attributes

All data is split up into two elements:

Entries, which are containers. It can be considered equivalent to an account (“this account exists or it does not”)
Attributes, which qualify the entry. These are also commonly called fields, elements or keys (“this account is called jdoe”)

2.2 Pivot attributes

To synchronize data, LSC must be able to match up entries in the source and in the destination. This is an important prerequisite to synchronizing your data: a unique identifier must be available in all entries and in both your source and your destination.

This unique identifier may be a combination of several fields (for example: surname and first name).

Commonly used pivot attributes include email addresses, or serial numbers (such as UUIDs).

2.3 One-to-one entry matching

LSC will try and match every entry in the source to one, and only one entry in the destination. Matching is done by searching on the pivot attributes (see details in the Configuration section below).

Synchronizing several entries to one, or one entry to several could be achieved by implementing multiple synchronizations, but is a hack.

2.4 One-way only

LSC synchronizations are one-way only: from a source to a destination.

It usually only makes sense to copy data in one direction. However, if you need to copy a different set of data back, you can simply implement a separate synchronization.

2.5 Four operations available

For every entry, LSC may perform one of the following operations (or nothing):

Add a new entry (if an entry from the source was not found in the destination)
Delete an old entry (if an entry in the destination was not found in the source)
Update an existing entry (if attributes vary between the destination and the calculated transformations from the source)
Rename an existing entry (if the LDAP DN should be changed)

Please note that one and only one of these operations is performed on each run. So, if an entry is renamed, but some of it’s attributes also need updating, this will only happen over two runs.

2.6 Transformations

… Work in progress …

3 Obtaining and installing LSC

3.1 Choosing the right version

Several versions of LSC are available. As with many Open Source projects, the main development focus is on one branch, while maintenance is performed on the previous branch. Choosing the right version is not always easy when starting out with new software. This section offers guidance.

3.1.1 Version numbering

A full version number looks something like 1.1.0. LSC version numbers are in two parts:

The first two digits represent the major branch number, for example 1.1.
The third digit represents a minor release within that branch, similar to a patch level.

A minor update (patch level increase, such as 1.1.0 to 1.1.1) never changes functionality, and is only released to fix bugs.

3.1.2 Current version

At the time of writing, the 1.2 branch is the most recent version available, and is fully supported.

The 1.1 branch is no longer actively developed, and will no longer be supported in the near future. The latest and most stable versions of LSC are always shown on the project’s website at http://lsc-project.org/.

Development work is currently transitioning between improving this branch, 1.2, and implementing new features for future versions.

3.2 Downloading and installing the software

3.2.1 Dependencies

To run LSC you need Sun’s Java Virtual Machine (JVM), version 1.5 or higher. Download and install Sun’s Java Runtime Edition (JRE), if you don’t already have it installed. Please note that it may be simpler to use a pre-packaged version from your operating system.

All other dependencies required by LSC are included in the download.

3.2.2 Downloading

In the past, two separate components were required to use LSC (lsc-core and lsc-sample). This is no longer the case. LSC is distributed like most programs, as an archive to download and install.

There are several formats available. They all lead to the same result, just choose your preference from the following:

Graphical installer based in a JAR file. After download, run this with java -jar filename.
Compressed archive in a gzipped tarball.
Compressed archive in a zip archive.

See all downloads at http://tools.lsc-project.org/files.

Note: .bz2 files can be decompressed using 7-Zip on Windows.

3.2.3 Installing

Depending on the packaging you chose, either run the graphical installer as a Java executable (java -jar filename), or extract the compressed archive to the location of your choice.

In either case, LSC will be installed in a self-contained directory, including all dependencies required to run.

Once installed, you should see the following folders in the installation directory:

bin (programs to launch and interact with LSC)
etc (configuration files)
lib (software dependencies)

4 Configuring LSC

There are several different aspects to configuring a connector using LSC:

Source and destination connector configuration
Data transformation configuration
Logging configuration

Within the installation directory, all configuration files are located in the etc/ directory. Most configuration is done in the lsc.properties file, except for logging which is setup in logback.xml. Each source connector may use additional configuration files - such as is the case for the database source connector used in db2ldap connectors.

4.1 Source and destination connector configuration

4.1.1 Matching up entries

This sections focuses specifically on the following properties ({src,dst} means “either src or dst”):

lsc.tasks.MyTask.{src,dst}Service.filterAll
lsc.tasks.MyTask.{src,dst}Service.pivotAttrs
lsc.tasks.MyTask.{src,dst}Service.filterId

In short, here is what happens when you run LSC in sync mode:

Once, on startup: search source directory with srcService.filterAll and read the srcService.pivotAttributes from each matching entry. This gives us a long list of attribute values (possibly couples or tuples, if you use two or more pivots).
For each value (or tuple): running through this list:
- Search the source directory using the srcService.filterId, replacing anything like {name} by the value for the attribute by that name read in as a pivot attribute. Read in the entry, or at least the attributes specified in srcService.attrs.
- Search the destination directory using the dstService.filterId, replacing anything like {name} by the value for the attribute by that name read in as a pivot attribute from the source. If an entry is found, read it in, or at least the attributes specified in dstService.attrs.
- Run through all syncoptions and attributes to build up what we “want” to be in the destination, compare it with what we just read from the destination, and apply any changes.

In clean mode, the opposite happens: LSC searches the destination with dstService.filterAll, reads in all the pivot attributes, and does a search with each of them on the source, using srcService.filterId.

Ldap Synchronization Connector (LSC) - User Guide