Ubuntu Manpage: pki-server-logging - PKI Server Logging Configuration

Provided by: pki-server_10.6.0-1ubuntu2_amd64

NAME

       pki-server-logging - PKI Server Logging Configuration

LOCATION

       /etc/pki/<instance>/logging.properties,      /var/lib/pki/<instance>/lib/log4j.properties,
       /etc/pki/<instance>/<subsystem>/CS.cfg

DESCRIPTION

PKI server logging can be configured using the following logging frameworks:

- java.util.logging (JUL) (https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html)
- Log4j (http://logging.apache.org/log4j/1.2/)
- Internal Logging

java.util.logging (JUL)
Tomcat uses JUL as the default logging framework. The configuration is described in
http://tomcat.apache.org/tomcat-7.0-doc/logging.html and
http://tomcat.apache.org/tomcat-8.0-doc/logging.html.

The default configuration is located at /usr/share/pki/server/conf/logging.properties.
During server deployment a link will be created at /etc/pki/<instance>/logging.properties.

By default only log messages with level WARNING or higher will be logged on the console
(i.e. systemd journal).

java.util.logging.ConsoleHandler.level = ALL
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

java.util.logging.SimpleFormatter.format = %4$s: %5$s%6$s%n

.level = WARNING
.handlers = java.util.logging.ConsoleHandler

The systemd journal can be viewed with the following command:

$ journalctl -u pki-tomcatd@<instance>.service

For more information see the following documents:

- https://docs.oracle.com/javase/8/docs/api/java/util/logging/ConsoleHandler.html
- https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html
- https://docs.oracle.com/javase/8/docs/api/java/util/logging/SimpleFormatter.html
- https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html

Log4j
The default Tomcat 7 classpath does include Log4j, but the server itself is not configured
to use Log4j for logging by default. However, since the Log4j is in the classpath the
RESTEasy will use Log4j for logging automatically (see
https://docs.jboss.org/resteasy/docs/3.0.6.Final/userguide/html/Installation_Configuration.html#RESTEasyLogging).

The default Log4j configuration is located at /usr/share/pki/server/conf/log4j.properties.
During server deployment a link will be created at
/var/lib/pki/<instance>/lib/log4j.properties.

By default only log messages with level WARN or higher will be logged on the console (i.e.
systemd journal).

log4j.appender.console = org.apache.log4j.ConsoleAppender
log4j.appender.console.Target = System.err
log4j.appender.console.layout = org.apache.log4j.PatternLayout
log4j.appender.console.layout.ConversionPattern = %p: %m%n

log4j.rootLogger = WARN, console

The default Tomcat 8 classpath does not include Log4j, so RESTEasy will use JUL instead.

For more information see the following documents:

- http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/ConsoleAppender.html
- http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Level.html
- http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html

Internal Logging
Each PKI subsystem uses an internal logging framework for debugging purposes.

The logging configuration is stored in /etc/pki/<instance>/<subsystem>/CS.cfg.

debug.enabled=true
debug.level=0
debug.filename=/var/lib/pki/<instance>/logs/<subsystem>/debug
debug.hashkeytypes=
debug.showcaller=false

The debug.enabled determines whether the debug log is enabled. By default it is enabled.

The debug.level determines the amount of details to be logged. The value ranges from 0
(most details) to 10 (least details). The default is 0.

The debug.filename determines the debug log file location. By default it is located at
/var/lib/pki/<instance>/logs/<subsystem>/debug.

The debug.hashkeytypes is a comma-separated list of additional components to log. By
default it's empty.

The debug.showcaller determines whether to include the caller information in the log
message. By default it's disabled.

CUSTOMIZATION

   java.util.logging (JUL)
       To customize JUL configuration, replace the link with a copy of the default configuration:

       $ rm -f /etc/pki/<instance>/logging.properties
       $ cp /usr/share/pki/server/conf/logging.properties /etc/pki/<instance>
       $ chown pkiuser.pkiuser /etc/pki/<instance>/logging.properties

       Then  edit  the  file as needed.  For example, to troubleshoot issues with PKI library add
       the following lines:

              netscape.level = ALL
              com.netscape.level = ALL
              org.dogtagpki.level = ALL

       To troubleshoot issues with RESTEasy add the following line (unless Log4j is installed  in
       Tomcat classpath):

              org.jboss.resteasy.level = ALL

       Then restart the server.

   Log4j
       To   customize  Log4j  configuration,  replace  the  link  with  a  copy  of  the  default
       configuration:

       $ rm -f /var/lib/pki/<instance>/lib/log4j.properties
       $ cp /usr/share/pki/server/conf/log4j.properties /var/lib/pki/<instance>/lib
       $ chown pkiuser.pkiuser /var/lib/pki/<instance>/lib/log4j.properties

       Then edit the file as needed.  For example, to troubleshoot issues with RESTEasy  add  the
       following line (unless Log4j is not installed in Tomcat classpath):

              log4j.logger.org.jboss.resteasy = ALL

       Then restart the server.

   Internal Logging
       To  customize  the internal logging configuration, edit the CS.cfg as needed, then restart
       the server.

AUTHORS

       Dogtag Team <pki-devel@redhat.com>.

COPYRIGHT