The Shibboleth V1 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.
CreateUsefulContainerLogs
- Scott Cantor
- Former user (Deleted)
Make your servlet container create useful logs
You need container logs to track down any errors that occur during the startup of the IdP servlet. As of Tomcat 5.5.9, Tomcat comes with JULI (http://jakarta.apache.org/tomcat/tomcat-5.5-doc/changelog.html): Java.Util.Logging Interface. The goal of JULI is to provide a logging mechanism that resembles the one in Tomcat4 (initially tomcat5 did not come with any logging built-in).
A more commonly used logging implementation is log4j. Shibboleth also uses log4j (and log4cpp). This logging implementation is more flexible and more performant, so you'll probably want to use that.
IMPORTANT
You should not install log4j both container-wide ("common" directory) AND for an individual webapp. Installing log4j in the common directory will also enable logging for all webapps, and thus enables you to configure all logging in the main log4j file. But if the webapp also includes a log4j library that will cause conflicts like log rotation problems which may cause logging to stop entirely after a rotate. If you want to use one log4j for the servlet container and the webapps, then you should REMOVE the log4j library from the Shibboleth webapp (remove it from the lib dir of the unpacked war or remove it from the package before you build the war).
Installing Log4j on Tomcat 5
Log4j is a powerful logging package that allows you to configure fine-grained logging for every application that supports it.
Information can be found at http://logging.apache.org/log4j/, and more specific information about settings is located at http://logging.apache.org/log4j/docs/api/.
Download and install commons-logging
Jakarta commons-logging is a common interface to a variety of logging API implementations. It functions as an abstraction layer between Tomcat and log4j. Tomcat has a dummy version bundled (commons-logging-api). You need the fully functional version, the dummy version is not enough!
- download a binary package from http://jakarta.apache.org/commons/logging/ (http://jakarta.apache.org/site/downloads/downloads_commons-logging.cgi)
- extract the package
- copy commons-logging.jar to %CATALINA_HOME%/common/lib/ (NOT the ...-api version)
Download and install log4j
- download a binary package from http://logging.apache.org/log4j/docs/index.html (http://logging.apache.org/site/binindex.cgi)
- extract the package
- copy dist/lib/log4j-x.x.x.jar to %CATALINA_HOME%/common/lib/
Configure Tomcat to use log4j
Please see http://logging.apache.org/log4j/docs/manual.html and http://logging.apache.org/log4j/docs/api/ for details about logging configuration options.
create a file called
log4j.properties
in %CATALINA_HOME%/common/classes/
Here's an example (contains three different appenders: one for Tomcat, Shibboleth and CAS):
#### Configures Log4j as the Tomcat system logger ####
# restart Tomcat for the changes to take effect (can be monitored by eg Spring framework for dynamic reloading)
# Configure the logger to output info level messages into a rolling logfile.
log4j.rootLogger=INFO, TOMCAT_APPENDER
#SSL debugging when running Tomcat stand-alone and not using the APR
#log4j.logger.org.apache.tomcat.util.net.jsse=DEBUG
log4j.logger.org.apache=INFO
#log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina]=DEBUG
#log4j.logger.org.apache.catalina.core=DEBUG
#log4j.logger.org.apache.catalina.realm=DEBUG
#log4j.logger.org.apache.catalina.session=DEBUG
#log4j.logger.org.apache.jasper.compiler.JspRuntimeContext=DEBUG
#log4j.logger.org.apache.struts=DEBUG
### cas-client ###
log4j.logger.edu.yale.its.tp.cas.client=INFO, SHIB_APPENDER
#log4j.logger.edu.yale.its.tp.cas=DEBUG, SHIB_APPENDER
### Shibboleth-IdP ###
log4j.logger.org.apache.xml.security=INFO, SHIB_APPENDER
#log4j.logger.org.apache.xml.security=DEBUG, SHIB_APPENDER
log4j.logger.edu.internet2.middleware.shibboleth=INFO, SHIB_APPENDER
#log4j.logger.edu.internet2.middleware.shibboleth.xml=DEBUG
#log4j.logger.edu.internet2.middleware.shibboleth.idp=DEBUG
#log4j.logger.edu.internet2.middleware.shibboleth.idp.IdPResponder=DEBUG
#log4j.logger.edu.internet2.middleware.shibboleth.idp.IdPConfigLoader=DEBUG
#log4j.logger.edu.internet2.middleware.shibboleth.aa=DEBUG
#log4j.logger.edu.internet2.middleware.shibboleth.aa.attrresolv=DEBUG
### WAYF ###
log4j.logger.edu.internet2.middleware.shibboleth.wayf=DEBUG, WAYF_APPENDER
### cas-server ###
log4j.logger.org.jasig.cas=INFO, CAS_APPENDER
#log4j.logger.org.jasig.cas.authentication=DEBUG
#log4j.logger.org.jasig.cas.web.flow.TicketGrantingTicketCheckAction=DEBUG
#log4j.logger.org.jasig.cas.services=DEBUG
#log4j.logger.org.jasig.cas.services.DefaultServiceRegistry=DEBUG
#log4j.logger.org.jasig.cas.ticket=DEBUG
#log4j.logger.org.jasig.cas.web.flow.X509CertificateCredentialsNonInteractiveAction=DEBUG
#log4j.logger.org.jasig.cas.adaptors.x509=DEBUG
#log4j.logger.org.jasig.cas.adaptors.ldap.authentication.principal.CredentialsToLDAPAttributePrincipalResolver=DEBUG
#log4j.logger.org.jasig.cas.adaptors.ldap=DEBUG
#log4j.logger.org.jasig.cas.adaptors.radius=DEBUG
log4j.logger.org.esupportail.cas.server.GenericHandler=INFO, CAS_APPENDER
log4j.logger.org.springframework=WARN, CAS_APPENDER
#log4j.logger.org.springframework.web.servlet.view=DEBUG
#log4j.logger.org.springframework.web.servlet.i18n=DEBUG
log4j.logger.org.quartz=INFO, CAS_APPENDER
# Configuration for a rolling log file ("tomcat.log").
log4j.appender.TOMCAT_APPENDER=org.apache.log4j.DailyRollingFileAppender
log4j.appender.TOMCAT_APPENDER.DatePattern='.'yyyy-MM-dd
# Edit the next line to point to your logs directory.
# The last part of the name is the log file name.
log4j.appender.TOMCAT_APPENDER.File=${catalina.home}/logs/tomcat.log
log4j.appender.TOMCAT_APPENDER.layout=org.apache.log4j.PatternLayout
#
# Print the date in ISO 8601 format
#log4j.appender.TOMCAT_APPENDER.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
log4j.appender.TOMCAT_APPENDER.layout.ConversionPattern=%d{HH:mm:ss,SSS} [%t] %-5p %m - %c [%d{yyyyMMdd}]%n
# Configuration for a rolling log file ("shibboleth-idp.log").
log4j.appender.SHIB_APPENDER=org.apache.log4j.DailyRollingFileAppender
log4j.appender.SHIB_APPENDER.DatePattern='.'yyyy-MM-dd
# Edit the next line to point to your logs directory.
# The last part of the name is the log file name.
log4j.appender.SHIB_APPENDER.File=${catalina.home}/logs/shibboleth-idp.log
log4j.appender.SHIB_APPENDER.layout=org.apache.log4j.PatternLayout
#
# Print the date in ISO 8601 format
#log4j.appender.SHIB_APPENDER.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
log4j.appender.SHIB_APPENDER.layout.ConversionPattern=%d{HH:mm:ss,SSS} %-5p %m - %c [%t;%d{yyyyMMdd}]%n
# Configuration for a rolling log file ("shibboleth-wayf.log").
log4j.appender.WAYF_APPENDER=org.apache.log4j.DailyRollingFileAppender
log4j.appender.WAYF_APPENDER.DatePattern='.'yyyy-MM-dd
# Edit the next line to point to your logs directory.
# The last part of the name is the log file name.
log4j.appender.WAYF_APPENDER.File=${catalina.home}/logs/shibboleth-wayf.log
log4j.appender.WAYF_APPENDER.layout=org.apache.log4j.PatternLayout
#
# Print the date in ISO 8601 format
#log4j.appender.WAYF_APPENDER.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
log4j.appender.WAYF_APPENDER.layout.ConversionPattern=%d{HH:mm:ss,SSS} %-5p %m - %c [%t;%d{yyyyMMdd}]%n
# Configuration for a rolling log file ("cas3-server.log").
log4j.appender.CAS_APPENDER=org.apache.log4j.DailyRollingFileAppender
log4j.appender.CAS_APPENDER.DatePattern='.'yyyy-MM-dd
# Edit the next line to point to your logs directory.
# The last part of the name is the log file name.
log4j.appender.CAS_APPENDER.File=${catalina.home}/logs/cas3-server.log
log4j.appender.CAS_APPENDER.layout=org.apache.log4j.PatternLayout
#
# Print the date in ISO 8601 format
#log4j.appender.CAS_APPENDER.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
log4j.appender.CAS_APPENDER.layout.ConversionPattern=%d{HH:mm:ss,SSS} %-5p %m - %c [%t;%d{yyyyMMdd}]%n
Configuration can be set for a certain kind of 'logger' element that is defined in the code of the webserver/application. You will notice exactly the same thing in the Shibboleth code. This configuration is hierarchical so you should definitely mind what you set the rootLogger to! 'Loggers' with no specific configuration will use the configuration of the rootLogger.
Let's review a part of this file briefly:
|
the rootLogger is put in level |
|
we want the appender with name 'TOMCAT_APPENDER' to rotate the logfile every day (there are a lot of kinds of appenders available, eg a JDBCappender) |
|
self-explanatory |
|
the location of the dailyRollingFile that will be created, notice that it is relative to catalina_home in this case |
|
see http://logging.apache.org/log4j/docs/api/(note that the other two loggers use a different pattern) |
Please do mind that putting things in DEBUG will cause a lot of output, especially when you put the rootLogger in DEBUG . This will slow Tomcat down noticeable. Do NOT put things in DEBUG in a production environment unless you have a VERY good reason to do so.
Activate the new configuration
Restart Tomcat and you will notice a few very interesting new files at %CATALINA_HOME%/logs