Author: amagyar
Date: Tue Oct 4 11:13:59 2022
New Revision: 1904396
URL: http://svn.apache.org/viewvc?rev=1904396&view=rev
Log:
KNOX-2816 Add missing documentationsKNOX-2668 Documentation for Log4j2 changes
and migration guide
Modified:
knox/trunk/books/2.0.0/config.md
Modified: knox/trunk/books/2.0.0/config.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/2.0.0/config.md?rev=1904396&r1=1904395&r2=1904396&view=diff
==============================================================================
--- knox/trunk/books/2.0.0/config.md (original)
+++ knox/trunk/books/2.0.0/config.md Tue Oct 4 11:13:59 2022
@@ -866,10 +866,127 @@ The Zookeeper remote alias service is de
#### Logging ####
-If necessary you can enable additional logging by editing the
`log4j.properties` file in the `conf` directory.
+If necessary you can enable additional logging by editing the `log4j2.xml`
file in the `conf` directory.
Changing the `rootLogger` value from `ERROR` to `DEBUG` will generate a large
amount of debug logging.
A number of useful, more fine loggers are also provided in the file.
+With the 2.0 release, Knox uses Log4j 2 instead of Log4j 1. Apache Log4j 2 is
the successor of Log4j 1, but it is incompatible with its predecessor.
+The main differene is that from now on Knox uses XML file format for
configuring logging properties instead of `.property` files.
+
+If you have an existing deployment with customized Log4j 1 `.property` files
you will need to convert them to the new Log4j 2 format.
+
+##### Launcher changes #####
+
+The JVM property name that specifies the location of the Log4j configuration
file, was changed to `log4j.configurationFile`.
+
+For example
+
+ -Dlog4j.configurationFile=gateway-log4j2.xml
+
+Instead of
+
+ -Dlog4j.configuration=conf/gateway-log4j.properties
+
+
+##### Configuration file changes #####
+
+Log4j 2 uses a different configuration file format than Log4j 1.
+
+ app.log.dir=logs
+ app.log.file=${launcher.name}.log
+ log4j.rootLogger=ERROR, drfa
+ log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+ log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+ log4j.appender.stdout.layout.ConversionPattern=%d{yy/MM/dd HH:mm:ss} %p
%c{2}: %m%n
+ log4j.appender.drfa=org.apache.log4j.DailyRollingFileAppender
+ log4j.appender.drfa.File=${app.log.dir}/${app.log.file}
+ log4j.appender.drfa.DatePattern=.yyyy-MM-dd
+ log4j.appender.drfa.layout=org.apache.log4j.PatternLayout
+ log4j.appender.drfa.layout.ConversionPattern=%d{ISO8601} %-5p %c{2}
(%F:%M(%L)) - %m%n
+ log4j.logger.org.apache.http.impl.conn=INFO
+ log4j.logger.org.apache.http.impl.client=INFO
+ log4j.logger.org.apache.http.client=INFO
+
+
+For example the equivalent of the above Log4j 1 config file looks like this:
+
+ <Configuration>
+ <Properties>
+ <Property name="app.log.dir">logs</Property>
+ <Property name="app.log.file">${sys:launcher.name}.log</Property>
+ </Properties>
+ <Appenders>
+ <Console name="stdout" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d{yy/MM/dd HH:mm:ss} %p %c{2}: %m%n"
/>
+ </Console>
+ <RollingFile name="drfa" fileName="${app.log.dir}/${app.log.file}"
filePattern="${app.log.dir}/${app.log.file}.%d{yyyy-MM-dd}">
+ <PatternLayout pattern="%d{ISO8601} %-5p %c{2} (%F:%M(%L)) -
%m%n" />
+ <TimeBasedTriggeringPolicy />
+ </RollingFile>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.http.impl.client" level="INFO" />
+ <Logger name="org.apache.http.client" level="INFO" />
+ <Logger name="org.apache.http.impl.conn" level="INFO" />
+ <Root level="ERROR">
+ <AppenderRef ref="drfa" />
+ </Root>
+ </Loggers>
+ </Configuration>
+
+Log levels can be set on individual Java packages similarly as before. The
Loggers inherit properties like logging level and appender types from their
ancestors.
+
+##### Log4j Migration #####
+
+If you have an existing Knox installation which uses the default Logging
settings, with no customizations, then you can simply upgrade to the new
version and overwrite the `*-log4j.property` files with the `*-log4j2.xml`
files.
+
+
+Old Log4j 1.x property files:
+
+ -rw-r--r-- 1 user group 3880 Sep 10 10:49 gateway-log4j.properties
+ -rw-r--r-- 1 user group 1481 Sep 10 10:49 knoxcli-log4j.properties
+ -rw-r--r-- 1 user group 1493 Sep 10 10:49 ldap-log4j.properties
+ -rw-r--r-- 1 user group 1436 Sep 10 10:49 shell-log4j.properties
+
+The new Log4j 2 XML configuration files:
+
+ -rw-r--r-- 1 user group 4619 Jan 22 2020 gateway-log4j2.xml
+ -rw-r--r-- 1 user group 1684 Jan 22 2020 knoxcli-log4j2.xml
+ -rw-r--r-- 1 user group 1765 Jan 22 2020 ldap-log4j2.xml
+ -rw-r--r-- 1 user group 1621 Jan 22 2020 shell-log4j2.xml
+
+If you have a lot of customizations in place, you will need to convert the
property files to XML file format.
+
+There is a third party script that helps you with the conversion:
+
+ https://github.com/mulesoft-labs/log4j2-migrator
+
+The final result is not always 100% correct, you might need to do some manual
adjustments.
+
+Usage:
+
+ $ groovy log4j2migrator.groovy log4j.properties > log4j2.xml
+
+
+The scripts uses ââAsyncLoggers by default which requires the
com.lmax:disruptor library which is not distributed with Knox by default.
+
+To avoid having this dependency you can replace all the `AsyncLogger` tags to
`Logger`s.
+
+ $ groovy log4j2migrator.groovy log4j.properties > log4j2.xml | sed
's/AsyncLogger/Logger/g'
+
+Pay attention to the custom date time patterns in the configuration file. The
script doesn't always convert them properly.
+
+You can find more information about the Log4j 2 configuration file format at
here: https://logging.apache.org/log4j/2.x/manual/configuration.html#XML
+
+
+##### Custom Appenders and Layouts #####
+
+Custom Appenders or Layouts based on the Log4j 1 API, are not going to work
with Log4j 2. Those need to be rewritten using the new API.
+
+The `AppenderSkeleton` class does not exist in Log4j 2, you should extend from
`AbstractAppender` instead.
+
+You can read more about extending Log4j 2 at:
https://logging.apache.org/log4j/2.x/manual/extending.html
+
#### Java VM Options ####
