- 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:
- PIP Service
Log when running PIP as a service.
- PIP Configurator
Log when using the PIP Configurator application.
Log changes made to identity data.
Audit logging is only used in “output” actions.
Logging for a specific policy.
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:
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.
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.
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
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:
- Open PIP Configurator
- Click Configuration -> General -> Log Settings
- Click Load log settings in log4j2.xml
- Change log settings as you see fit
- Click Save log setting
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.
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
- Open PIP Configurator
- Click Policies -> Your Policy
- Click on Policy Specific Logging
- Click Log to separate file checkbox to enable policy logging for this policy
- Enable policy logging for the first time for this policy
- Click Edit logger name
- Give the logger a name. Note: The logger name must be unique.
- Click Yes to create the new logger
- Edit the for an existing policy
- Click Edit logger name
- Change the logger a name. Note: The logger name must be unique.
- Click Yes to update with then new name
- Click Load log settings from log4j2.xml button
- 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
DISCLAIMERInformation provided in this document is for your information only. PhenixID makes no explicit or implied claims to the validity of this information. Any trademarks referenced in this document are the property of their respective owners.
The origin of this information may be internal or external to PhenixID. PhenixID makes all reasonable efforts to verify this information.
PhenixID - support.phenixid.se