PSD1192 – Configuration of Log4j2 in PIP

Prerequisite

• PhenixID Identity Provisioning (PIP) 6.1.4 or later

Configure Log4j2 in PIP

This PSD describes how to configure logging for PIP 6.1.0 or later using Apache Log4j2. In PIP 6.0.0, Log4j1 was replaced with Log4j2.
How to migrate log settings from PIP 5.4.1 or earlier is covered in the following PSD, PSD1197.

What can be logged in PIP?

Four (4) different things in PIP can be logged using Log4j2:

1. PIP Service
   Log when running PIP as a service.
   
2. PIP Configurator
   Log when using the PIP Configurator application.
   
3. Audit
   Log changes made to identity data.
   Audit logging is only used in “output” actions.
   
4. Policy
   Logging for a specific policy.

Configure logging

Logging is enabled by default except for policy logging. If you like to change the default behaviour of how PIP logs data you can do that using:

• PIP Configuration UI
  In the UI there are a number of parameters to configure to make PIP log the way you like. All changes of logging is stored in log4j.xml and not config.aam except the logger name that is also stored in config.aam.
  (in previous version of PIP, all log settings was stored in config.aam).
  Note. Changed to log in PIP UI is only supported if config.aam is loaded. If you load another configuration file, for example config_test.aam, you will not be able to change log settings)
• Directly in log4j2.xml
  If you are skilled in log4j2 then you might like to configure log settings for PIP directly in the log4j2.xml file.
  Note. If you do configuration directly in log4j2.xml, make sure you disable PIP Configuration to write to the log-file.

Loggers and appenders

In Log4j2 there are two basic components to understand, loggers and appenders:

• Logger
  A logger defines what to log. See example in document. The logger name is the link/key between PIP (config.aam) and log4j2.xml.
  You will define the logger name if you configure policy based in the PIP UI. Logger name for PIP Service, PIP Configurator and PIP Audit can not be changed.
  Note. Only logger name using A-Z, a-z or 0-9 are supported.
  
• Appender
  The appender is the part of a logging system that’s responsible for sending the log messages to some destination or medium. See example below.

By default all log configuration is done in the PIP Configurator. The logger and appender are already created for the service, the configurator and audit. When you enable policy specific logging you will give the log-file a name which also will be the name of the logger, this name must be unique. That will be the link/key between the PIP configurator and the log4j2.xml file. When enabling policy specific logging an appender will also be created for the logger by the PIP Configurator.

Link to Apache Log4j2 site

This PSD gives some examples and understanding how do use Log4j2 with PIP, but since Log4j2 is a Java-based logging utility created by Apache there are many ways to configure logging.
Please read more about Log4j2 on the Apache project web page.
Remember that all general logging can be done using the PIP Configuration to hide the complexity in the log4j2.xml file.

Configuration overview

The log configuration file, log4j2.xml

Configuration is stored in a file called log4j2.xml. The file is located in the main folder for PIP. (\..\PhenixID\Provisioning)
If the file does not exist, PIP will create it with default configuration. Updates to the file can be done directly in the file or by using PIP Configurator. If you do it directly make sure you disable PIP Configuration to write to the log-file.

The log4j2_template.xml template file

The \..\PhenixID\Provisioning folder also contains a file named log4j2_template.xml. This file will be overwritten for every upgrade, the file contains the default configuration for the installed version. PIP upgrades will never update the log4j2.xml file, you need to manually update the log4j2.xml file from the template if any changes has been made that you like to use. Check out every release note if any update is available.

Restart service on change

Whenever you update log settings in PIP Configurator or directly in the PIP log4j2.xml file, the PIP service or PIP configurator needs to be restarted.

Configure using PIP Configurator UI

Overview

In the PIP Configuration UI you can manage log settings. All values you see are fetched from the log4j2.xml file. Since the values are not stored in config.aam you need in each log panel load and save the data since it will be written to a separate file, log4j2.xml.

When configuring logs in PIP Configurator ony the settings you change will be saved to log4j2.xml. If you for some reason have custom settings in log4j2.xml they will not be overwritten, only the values you change in PIP Configurator and if you click on Save log settings will be saved.

Configuration for PIP service or PIP configurator

The log settings for the PIP Service and the PIP Configuration are the same so it will be explained in the same section.

To change log settings for PIP service or PIP configurator:

1. Open PIP Configurator
2. Click Configuration -> General -> Log Settings
3. Click Load log settings in log4j2.xml
4. Change log settings as you see fit
5. Click Save log setting

Level

First you choose log level:
Fatal, Error, Warn, Info, Debug or Trace.
In a production environment where PIP is working as expected, Info is recommended as log level.

Roll file using date

For each new day a new log-file will be created.

configurator.log
configurator-2022-05-03.log
configurator-2022-05-04.log
service.log
service-2022-05-04.log
service-2022-05-05.log

Delete files using date

If you have no limit for how many log files that might be created you might run into a disk issue. If you set a value, for example 90 days, PIP will removed each file every day that turn 90 days old.

Roll file using size

PIP will create a new log-file when a log file reach a specific size. This is good to now have log-files that will be very large and therefor hard to manage if you need to look inside them.

configurator.log
configurator-1.log
configurator-2.log
service.log
service-1.log
service-2.log

Delete files using number of files

If you have no limit for how many log files that might be created you might run into a disk issue. If you set a value, for example 90, PIP will removed each file every time a file becomes the 91st.

Using both date and size

If you have both rolling by date and sized enabled, see below example.

configurator.log
configurator-2022-05-03-1.log
configurator-2022-05-03-2.log
configurator-2022-05-03-3.log
configurator-2022-05-04-1.log
service.log
service-2022-05-04-1.log
service-2022-05-04-2.log
service-2022-05-05-1.log

Configuration of PIP Audit

The log settings for for PIP Audit is done the same way as for the PIP Service and the PIP Configuration. However there are two things to understand.

• Log level will always be INFO, that is why you cannot choose log level.
• Audit logging is only used in “output” actions .eg.

Example of an audit log where a user is created in Active Directory:

[EVENT] 2022-05-03 16:11:27.542 plugins.v3.CreateLDAPObject Created object "CN=KalleTeacher,OU=Teacher,OU=School_1,OU=PSD1184_SchoolUseCase,DC=demo,DC=phenixid,DC=net" in directory "LDAP - PSD1184" with the attributes: [sAMAccountName = KalleTeacher][givenName = Kalle][sn = Teacher][userAccountControl = 544][displayName = Kalle Teacher][objectClass = user][unicodePwd = ]

Log a specific policy

To isolate log data from a specific PIP policy and send to a separate file, you need to enable custom logging for each policy of interest.
Note: All policy specific logs are stored under the log path (/logs) of PIP.
Note2: PIP supports subfolder structures. You might like to have a policy logging in a separate folder.

How to configure policy logging

1. Open PIP Configurator
2. Click Policies -> Your Policy
3. Click on Policy Specific Logging
4. Click Log to separate file checkbox to enable policy logging for this policy
5. Enable policy logging for the first time for this policy
   1. Click Edit logger name
   2. Give the logger a name. Note: The logger name must be unique.
   3. Click Yes to create the new logger
6. Edit the for an existing policy
   1. Click Edit logger name
   2. Change the logger a name. Note: The logger name must be unique.
   3. Click Yes to update with then new name
7. Click Load log settings from log4j2.xml button
8. Update log setting as you wish. See earlier in this PSD what then different log setting means.

Example of policy logging in PIP UI

Below is a screenshot of the policy logging tab on a policy.

Example of policy in log4j2.xml

If you have created policy logging for policy above then you will find the following configuration in the log4j2.xml file.
Note that both the logger and the appender component are created automatically when you click Save log settings in PIP UI.
Below is the logger component:

Below is the appender component associated with the logger component above.

Export and import policy log configuration

If you like to export one or several polices from a PIP 6.1.0 installation and import to another installation you can do so. For example from a test environment to a production environment.

Export log data on a policy

There is no way from the PIP UI to export only the log configuration from a policy. The log data will be exported together with the policy data when you export a policy.

Of course you can always open the log4j2.xml file to extract the logger and appender for a specific policy.

Import log data to a policy

There is no way from the PIP UI to import only the log configuration from a policy. You choose when you import the policy if you also would like to import/update the configuration data for the policy.

When import you can choose three things regarding policy log import:

• Skip import
• Import only new configure log
• Import all log settings. (this will overwrite all current log settings.)

Migrate from earlier version of PIP

If you upgrade from a version prior to PIP 6.1.4 and you have several policies with logging configured, then you need to update the polices to support Log4j2.

For more information about this, please read PSD1197