Migration to Log4j version 2

XTAM logging subsystem including integration with SIEM systems or Windows Event logging is based on log4 module.

Default XTAM installation ships with log4j version 1 embedded. Benefits of migrating the deployment to log4j version 2 include the option to integrate with syslog SIEM systems using TCP protocol and the option to change logging configuration for different system components without restarting of the system.

 

The following guide described steps needed to complete to switch XTAM deployment to log4j version 2.

Migration Guide

  1. Download and uncompress log4j2 archive: https://bin.xtontech.com/product/xtam-log4j2.zip

  2. Stop PamManagement / pammanager service.

  3. Delete the following files from two folders:

    $XTAM/web/webapps/xtam/WEB-INF/lib/

    $XTAM/web/webapps/xtamWorker/WEB-INF/lib/

    slf4j-api-1.7.5.jar

    slf4j-log4j12-1.7.22.jar

  4. Copy file conf/log4j2.pam.xml from the downloaded archive to $XTAM/web/conf/ folder

    Copy all files from lib folder from the downloaded archive to $XTAM/web/lib/ folder

  5. Edit
    1. for Linux: edit file $XTAM/bin/pammanager

      replace line:

      Copy
      export JAVA_OPTS="$DERBY_OPTS -Dlog4j.configuration=file://$CATALINA_BASE/conf/log4j.pam.properties -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true"

      with

      Copy
      export JAVA_OPTS="$DERBY_OPTS -Dlog4j.configurationFile=file://$CATALINA_BASE/conf/log4j2.pam.xml -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true"

      Refresh the service configuration if needed.

    2. for Windows: edit file $XTAM/bin/ServiceManagement.cmd

      replace line:

      Copy
      @set JAVA_OPTS=%DERBY_OPTS% -Dlog4j.configuration=file:///%CATALINA_BASE%\conf\log4j.pam.properties -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

      with

      Copy
      @set JAVA_OPTS=%DERBY_OPTS% -Dlog4j.configurationFile=file:///%CATALINA_BASE%\conf\log4j2.pam.xml -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

       

      From an administrative command prompt, navigate to $XTAM_HOME and run the command:

      Copy
      bin\ServiceManagement.cmd remove

      When the above command completes successfully, run the command:

      Copy
      bin\ServiceManagement.cmd install
  6. Start PamManagement / pammanager service.

Roll back to Log4j version 1

  1. Download and uncompress log4j2 archive: https://bin.xtontech.com/product/xtam-log4j2.zip

  2. Stop PamManagement / pammanager service.

  3. Copy the following files to two folders from lib1 folder of the uncompressed archive:

    $XTAM/web/webapps/xtam/WEB-INF/lib/

    $XTAM/web/webapps/xtamWorker/WEB-INF/lib/

    lib1/slf4j-api-1.7.5.jar

    lib1/slf4j-log4j12-1.7.22.jar

  4. Delete the following files from $XTAM/web/lib folder

    disruptor-3.4.2.jar

    log4j-api-2.14.0.jar

    log4j-core-2.14.0.jar

    log4j-slf4j18-impl-2.14.0.jar

    slf4j-api-1.8.0-beta4.jar

  5. Edit
    1. for Linux: edit file $XTAM/bin/pammanager

      replace line:

      Copy
      export JAVA_OPTS="$DERBY_OPTS -Dlog4j.configurationFile=file://$CATALINA_BASE/conf/log4j2.pam.xml -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true"

      with

      Copy
      export JAVA_OPTS="$DERBY_OPTS -Dlog4j.configuration=file://$CATALINA_BASE/conf/log4j.pam.properties -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true"

      Refresh the service configuration if needed.

    2. for Windows: edit file $XTAM/bin/ServiceManagement.cmd
    3. replace line:

      Copy
      @set JAVA_OPTS=%DERBY_OPTS% -Dlog4j.configurationFile=file:///%CATALINA_BASE%\conf\log4j2.pam.xml -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

      with

      Copy
      @set JAVA_OPTS=%DERBY_OPTS% -Dlog4j.configuration=file:///%CATALINA_BASE%\conf\log4j.pam.properties -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

      From an administrative command prompt, navigate to $XTAM_HOME and run the command:

      Copy
      bin\ServiceManagement.cmd remove

      When the above command completes successfully, run the command:

      Copy
      bin\ServiceManagement.cmd install
  6. Start PamManagement / pammanager service.

Adding Syslog configuration to log4j2

To add Syslog appender add the following line before <Async name="all"> tag (replace HOST with the real Syslog host, edit port 514 and use UDP or TCP as a protocol):

Copy
        <Syslog name="syslog" host="HOST" port="514" protocol="UDP" appName="xtam" id="xtam" newLine="true"/>

and add Async appender reference so it will look like this one below:

Copy
        <Async name="all">
            <AppenderRef ref="console"/>
            <AppenderRef ref="file"/>
            <AppenderRef ref="syslog"/>
        </Async>