Migration to Log4j version 2

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

Default PAM 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 PAM deployment to log4j version 2.

Please read the entire procedure outlined in the article before beginning. If you have any questions, please contact the Support team: https://support.imprivata.com/.

Migration Guide

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

  2. Stop PamManagement / pammanager service.

  3. Delete all files with names starting with slf4j* or log4j* from two folders:

    4. $PAM_HOME/web/webapps/xtam/WEB-INF/lib/

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

    If a PAM update is done manually, not through the PAM web UI, these deleted files will be added back. Files slf4j-api-1.7.5.jar (or slf4j-api-2.0.7.jar) & log4j-1.2.17.jar will need to removed again after updating.

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

  5. Copy all files from lib folder from the downloaded archive to $PAM_HOME/web/lib/ folder.

  6. Edit:

    1. For Linux edit file $PAM_HOME/bin/pammanager

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

      with 

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

    2. After making the modifications above, this section will look similar to this example:

      3. export JAVA_OPTS="$DERBY_OPTS -Dlog4j.configurationFile=file://$CATALINA_BASE/conf/log4j2.pam.xml -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true -Dlog4j2.formatMsgNoLookups=true --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.xml/com.sun.org.apache.xerces.internal.util=ALL-UNNAMED --add-opens java.base/sun.security.provider=ALL-UNNAMED”

    3. Refresh the service configuration if needed.

    4. For Windows: edit file $PAM_HOME/bin/ServiceManagement.cmd

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

      with

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

    5. After making the modifications above, this section will look similar to this example:

      6. @set JAVA_OPTS=%DERBY_OPTS% -Dlog4j.configurationFile=file:///%CATALINA_BASE%\conf\log4j2.pam.xml -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true -Dlog4j2.formatMsgNoLookups=true --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.xml/com.sun.org.apache.xerces.internal.util=ALL-UNNAMED --add-opens java.base/sun.security.provider=ALL-UNNAMED

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

      Copy 
      bin\ServiceManagement.cmd remove

      When the above command completes successfully, run the command:

      Copy 
      bin\ServiceManagement.cmd install

      Note: The PamManagement service resets to the default Local System account Log on property once this service for PAM is reinstalled. If you are using a Log account other than an Local System account for this service then you must restore it prior to restarting the PamManagement service. Navigate to Services on Windows and find PamManagement, right-click and select Properties. Go to the Log on tab, select This account: and restore the required service account.

      PamManagement-Property.png

  7. Start PamManagement / pammanager service.

The logging level within PAM using Log4j version 2, can be configured using the file log4j2.pam.xml.

Roll back to Log4j version 1

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

  2. Stop PamManagement / pammanager service.

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

    4. $PAM_HOME/web/webapps/xtam/WEB-INF/lib/

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

    lib1/slf4j-api-1.7.5.jar

    lib1/slf4j-log4j12-1.7.22.jar

    lib1/log4j-1.2.17.jar

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

    5. disruptor-3.4.4.jar

    log4j-api-2.23.1.jar

    log4j-core-2.23.1.jar

    log4j-slf4j-impl-2.23.1.jar

    slf4j-api-1.7.36.jar

  5. Edit:

    1. For Linux: edit file $PAM_HOME/bin/pammanager

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

      with

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

    2. After making the modifications above, this section will look similar to this example:

      3. export JAVA_OPTS="$DERBY_OPTS -Dlog4j.configuration=file://$CATALINA_BASE/conf/log4j.pam.properties -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true -Dlog4j2.formatMsgNoLookups=true -Dlog4j2.formatMsgNoLookups=true --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.xml/com.sun.org.apache.xerces.internal.util=ALL-UNNAMED --add-opens java.base/sun.security.provider=ALL-UNNAMED”

      Refresh the service configuration if needed.

    3. For Windows: edit file $PAM_HOME/bin/ServiceManagement.cmd

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

      with

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

    4. After making the modifications above, this section will look similar to this example:

      5. @set JAVA_OPTS=%DERBY_OPTS% -Dlog4j.configuration=file:///%CATALINA_BASE%\conf\log4j.pam.properties -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true -Dlog4j2.formatMsgNoLookups=true --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.xml/com.sun.org.apache.xerces.internal.util=ALL-UNNAMED --add-opens java.base/sun.security.provider=ALL-UNNAMED

      From an administrative command prompt, navigate to$PAM_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.

The logging level within PAM using Log4j version 1, can be configured using the file log4j.pam.properties

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). The following lines should be added to the log4j2.pam.xml file:

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>

Restart the PamManagement service to reflect the added configuration.