Upgrade from 2.2

When installing the 2.3 (or newer) version of LSC, you should take care about these notes:

Upgrade version in lsc.xml

A new xsd schema has been provided to validate the lsc.xml configuration file.

You must upgrade the version to 2.3. For example, change this section of lsc.xml:

<lsc xmlns="http://lsc-project.org/XSD/lsc-core-2.2.xsd" revision="0">

into:

<lsc xmlns="http://lsc-project.org/XSD/lsc-core-2.3.xsd" revision="0">

parameters getAllFilter, getOneFilter, and cleanFilter have been DEPRECATED

They will still work for some time, but you are encouraged to migrate your configuration.

getAllFilter has been replaced by allEntriesFilter
getOneFilter has been replaced by oneEntryFilter
cleanFilter has been replaced by cleanEntryFilter

The new filter parameters are considered as scripts that will be evaluated as described in scripting section.

The migration consists in:

renaming the parameters,
surrounding the filters by double-quotes (”) to evaluate them as strings, and
replacing the placeholders {pivotAttributeName} by the pivotAttributes array: pivotAttributes["pivotattributename"], with pivotattributename written in lowercase.

For example, transform:

<getOneFilter>
    (&amp;(objectClass=inetorgperson)(mail={mail}))
</getOneFilter>

into:

<oneEntryFilter>
    "(&amp;(objectClass=inetorgperson)(mail=" + pivotAttributes["mail"] + "))"
</oneEntryFilter>

For more information, give a look to the ldap source and ldap destination services documentation.

Mixing sync and async task in the same run is not supported anymore

In LSC 2.2, there was a regression causing an abnormal sync and clean task run when using flag -a all. See https://github.com/lsc-project/lsc/issues/465 issue for more details. The regression has been fixed in 2.3, but the usage of mixed tasks is not possible anymore. You must now run either sync or async tasks.

New parameter bypassOneEntry

In LSC 2.3, you can now take advantage of a bypassOneEntry parameter, that allows you to fetch all attribute values during allEntries step. This parameter is available only for LDAP source service. See ldap source service documentation for more information.

Upgrade from 2.1

Install the new version, through packages or tarball. Here are some tips to adapt your current configuration to this new version.

Installation and requirements

As described in installation and requirements sections, there are somes changes:

LSC 2.2 is bundled only for RHEL-like systems 8 and 9, and debian-like systems 11 and 12
LSC 2.2 packages now require Java 21 for running. However, it is still compatible with java 11 and 17 if you build the code yourself.
the GPG key signing the packages has changed to lsc-project-securoty.gpg. You must import this new key.
Nagios plugins are now in the nagios-plugins-lsc package, you must install it if you need them.
HOME directory for lsc user has been moved from /etc/lsc to /var/lib/lsc. The package should do the upgrade automatically, but if you have customized the HOME directory, you should do the change by yourself. In this case, take care to define a HOME directory writable by lsc user, else graalvm would fail to start.

Scripting

The supported java versions aren’t handling Javascript code the same way.

If you have some javascript code in your tasks, be sure to read the scripting part of the documentation.

Most of the time, removing js: from the datasets is enough.

XML namespace

Update all configuration files to use the 2.2 XML namespace:

<lsc xmlns="http://lsc-project.org/XSD/lsc-core-2.2.xsd" revision="0">

Logging configuration

The logback.xml file has been improved.

You are encouraged to adapt your specific logback.xml configurations if you have modified them.

There are two evolutions:

Remove the logback initialization blathering at startup. Add these lines in the <configuration> section:

<!-- Stop logback initialization blathering at startup -->
<statusListener class="ch.qos.logback.core.status.NopStatusListener" />

The layout sections must now be surrounded by an encoder tag. You should add this <encoder> tag. For example:

<!-- Standard output to console -->
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
                <layout class="org.lsc.utils.output.LdifLayout">
                        <Pattern>%date{MMM dd HH:mm:ss} - %-5level - %message%n</Pattern>
                </layout>
        </encoder>
</appender>

Google Apps Destination service

This service is obsolete and has been removed in 2.2 version.

Audits

Audit configuration has been removed in 2.2.

If you have some configuration sections containing:

<audits>
  <audit>
    ...
  </audit>
</audits>

You must remove them and use logback configuration instead.

Behavior change for multi-valued attribute replacement

Before version 2.2, during an entry update, LSC behavior was to systematically replace all values for attributes in FORCE policy.

This could lead to slow modifications, especially for entries with many values, like groups holding many members. However, sometimes it’s cheaper to only add the missing values plus remove the extra values.

LSC 2.2 takes this problematic into consideration.

If (number of missing values + number of extra values) < number of expected values after modification, then LSC applies 2 operations:

1 add of missing values
1 delete of extra values

else, it performs a full replace with all values.