PSD1197 – Migrate to Log4j2

Prerequisite

• PhenixID Identity Provisioning 6.1.4 or later
• pip-log-migration-1.2.jar (download link in document)
  Version 1.2 support logs stored in subfolders

Overview

This document describes how to use a tool to easily migrate policy specific logging from Log4j1 (pre PIP 6.0.0) to Log4j2 (PIP 6.1.4 or later).
If you have a copy prior to PIP 6.1.4, make sure you get a later copy of the installer before you proceed.

If you are looking for a general understanding for how logging works in PIP 6.x using Log4j2, please read PSD1192.

Migration steps in short (all steps are explained in detailed later in PSD)

1. Prepare for migration and download application
   Upgrade or do a new install of PIP 6.1.0 or later.
   If you do a new install, make sure you have access to config.aam from the version you want to migrate from.
2. Run the migration tool
   1. A file called config-migrated.aam is created
   2. A file called log4j2-migrated.xml is created
3. Rename files and start PIP
   1. Rename the the current config.aam and log4j2.xml to ORG
   2. Rename config-migrated.aam to config.aam
   3. Rename log4j2-migrated.xml to log4j2.xml
   4. Start PIP Configurator or PIP Service
4. Verify migration
5. Migration complete!

Tool only for migrating policy specific logging

Note. The tool below is only to be used to migrating policy specific logging. You will only run the migration tool once.

Migration

1. Prepare for migration and download application

1. Make sure you run PIP 6.1.4 or later. You have either:
   1. upgraded from a previous version of PIP. Make sure you have a copy/backup of the drive:\..\PhenixID\Provisioning.
   2. a new clean installation of PIP and access to the config.aam for the version you want to migrate from
2. Stop PIP service
3. Make sure PIP configurator is not running
4. Download the migration application pip-log-migration-1.2.jar.
   Click this LINK to download.
5. Move pip-log-migration-1.2.jar to the drive:\..\PhenixID\Provisioning folder

2. Run the migration tool

1. Open a CMD prompt as administrator
2. Go to drive:\..\PhenixID\Provisioning
3. Add command
   jre\bin\java -Dfile.encoding=UTF-8 -jar pip-log-migration-1.2.jar config.aam X
   Note 1. config.aam is the config file for the previous version of PIP.
   1. 1. A – Roll log file based on file size (this was the default configuration using Log4j1, so current configuration on a policy will be the same in Log4j2)
         Example of command where you like to keep current configuration.
         pip-log-migration-1.2.jar config.aam A
      2. B – Roll log file based on date value
         (if you add a value, for example 90, the rolling date will 90. If you do not set a value there will be no rolling date value.)
         Example of command where you like to have 90 days.
         pip-log-migration-1.2.jar config.aam B 90
      3. C – Roll log file on date and file size value
         Example of command where you like to have 90 days and keep current configuration for file size rolling.
         pip-log-migration-1.2.jar config.aam C 90
      4. Press Enter to run command
4. If successful you should in the CMD see a result as stated below:
   Note. Screenshot is an earlier version of the migration tool
   
5. You should also in the file system find to new files, see below.
   Note. Screenshot is an earlier version of the migration tool
   

Note 1. The config.aam and the log4j2.xml file is still the same as before migration. The updated config.aam that works with the log4j2.xml are the files with -migrate at the end. See next section.

Note 2. Any characters in the logger name that are not A-Z, a-z or 0-9 . (dot), -(hyphen) or _ (underscore) is NOT supported. The UI will state that if you try to use something else.

3. Rename files and start PIP

Make PIP use the migrated files instead of the default.

1. Open a file browser
2. Go to drive:\..\PhenixID\Provisioning
3. Move or rename config.aam and log4j2.xml file
4. Rename the following files as stated below
   1. config-migrated.aam -> config.aam
   2. log4j2-migrated.xml -> log4j2.xml
5. Start PIP Configurator

4. Verify migration

To explain this we will use a policy in our environment called PIP Policy 1

4.1 Screenshot from previous version

This is a before screenshot taken from a PIP 5.4.1 environment for the example policy.

I have run the migration tool using this configuration:
pip-log-migration-1.2.jar config.aam C 90

4.2 Screenshot taken after migration from PIP Configurator

This is an after screenshot taken from a PIP 6.1.0 environment.

4.2 Screenshot taken from log4j2.xml after migration

This is an after screenshot taken from a PIP 6.1.0 environment of the migrated logger and the migrated appender

4.2.1 Screenshot of migrated logger in log4j2.xml

4.2.2 Screenshot of migrated appender in log4j2.xml

5. Migration complete!

Start PIP Service or PIP Configurator.

Verify for one of the migrated policies that log data is updated in the corresponding log file.