View source for Debugging OpenKM with JBoss

{{TOCright}} __TOC__
JAAS uses a service provider approach to its authentication features, meaning that it is possible to configure different login modules for an application without changing any code. The application remains unaware of the underlying authentication logic. It's even possible for an application to contain multiple login modules, somewhat akin to a stack of authentication procedures.

OpenKM relies on the authentication of the standard JAAS implemented in the JBoss application server. JBoss comes with some interesting modules which can be used to authenticate against a plain-text file, a database or an LDAP, for example. On recent versions, OpenKM uses the DatabaseServerLoginModule class to manage authentication. 

{{Note|The JBoss security is configured in the file ''$JBOSS_HOME/server/default/conf/login-config.xml''.}}

You can debug your OpenKM installation using the JBoss logging facility. This is an useful thing when you have problems with your configuration. Default OpenKM installation tries to log important events like errors and warnings. Is possible to change this configuration editing the file ''$JBOSS_HOME/server/default/conf/jboss-log4j.xml''.

Default JBoss log configuration can generate a lot of messages. These files are stored at ''$JBOSS_HOME/server/default/log''. It is configured to use the DailyRollingFileAppender. This appender create a new log file for every day. This is better than have a unique huge log file, os course. The rollover is performed at midnight each day, but you can configure it to make the rollover every hour (uncomment the proper line).

<source lang="xml">
<!-- A time/date based rolling appender -->
<appender name="FILE"
          class="org.jboss.logging.appender.DailyRollingFileAppender">
   <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
   <param name="File" value="${jboss.server.log.dir}/server.log"/>
   <param name="Append" value="false"/>
   <!-- Rollover at midnight each day -->
   <param name="DatePattern" value="'.'yyyy-MM-dd"/>
   <!-- Rollover at the top of each hour
   <param name="DatePattern" value="'.'yyyy-MM-dd-HH"/>
   -->
   <layout class="org.apache.log4j.PatternLayout">
      <!-- The default pattern: Date Priority [Category] Message\n -->
      <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
      <!-- The full pattern: Date MS Priority [Category] (Thread:NDC) Message\n
      <param name="ConversionPattern" value="%d %-5r %-5p [%c] (%t:%x) %m%n"/>
      -->
   </layout>
</appender>
</source>

You can reduce the amount of log messages produced by OpenKM, or can increase them. In this example we limit the log messages produced by the class OKMAccessManager for those of type ERROR.

<source lang="xml">
<category name="com.openkm.core.OKMAccessManager">
   <priority value="ERROR" />
</category>
</source>

If you create this configuration:

<source lang="xml">
<category name="com.openkm">
   <priority value="DEBUG" />
</category>
</source>

All the log messages generated by OpenKM will be shown. As you can see, you can increase debug messages in some parts of OpenKM to check a determinate behavior.

== Debugging JAAS configuration ==
If you are trying to setup another authentication source different from the default provided by OpenKM, you can afford some problems. The JBoss '''login-config.xml''' is supposed to have the right configuration, but you can't log into the application. The most common case is a bad or missing JAAS configuration. So if you need to debug the JAAS, you can add to the '''$JBOSS_HOME/server/default/conf/jboss-log4j.xml''' file the following:

<source lang="xml">
<category name="org.jboss.security">
   <priority value="TRACE" class="org.jboss.logging.XLevel"/>
   <appender-ref ref="SECURITY_F"/>
</category>
<appender name="SECURITY_F" class='org.jboss.logging.appender.DailyRollingFileAppender'>
   <param name="Append" value="true"/>
   <param name="DatePattern" value="'.'yyyy-MM-dd"/>
   <param name="File" value="${jboss.server.home.dir}/log/jboss.security.log"/>
   <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d{ABSOLUTE} %-5p [%c] %m%n"/>
   </layout>
</appender>
</source>

This is more or less in the middle of the file, just where the <category-name> section begins. And you should look at this new log file:

 $ tailf -f $JBOSS_HOME/server/default/log/jboss.security.log

== Email error notification ==
Always is good idea to be notified when things goes wrong. There are some log appenders that can help you. The SMTPAppender will mail you log messages with threshold ERROR by default. You can lower this threshold, but you will got lots of useless mail messages. Here you must configure some properties:

* '''To''': The mail account where the messages will arrive.
* '''From''': You can set it simply as noreply@your-domain.com.
* '''Subject''': Here you can specify the subject of the mail. If you have several OpenKM installations, you can create a filter in your mail client using this value.
* '''SMTPHost''': The mail server server. Can be localhost if there is a mail server installed in this computer.

<source lang="xml">
<!-- EMail events to an administrator -->
<appender name="SMTP" class="org.apache.log4j.net.SMTPAppender">
  <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
  <param name="Threshold" value="ERROR"/>
  <param name="To" value="admin@myhost.domain.com"/>
  <param name="From" value="nobody@myhost.domain.com"/>
  <param name="Subject" value="JBoss Sever Errors"/>
  <param name="SMTPHost" value="localhost"/>
  <param name="BufferSize" value="10"/>
  <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="[%d{ABSOLUTE},%c{1}] %m%n"/>
  </layout>
</appender>
</source>

In Unix / Linux systems there is a centralized log manager called syslog. You can configure Log4J to use this system using the SyslogAppender:

<source lang="xml">
<!-- Syslog events -->
<appender name="SYSLOG" class="org.apache.log4j.net.SyslogAppender">
  <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
  <param name="Facility" value="LOCAL7"/>
  <param name="FacilityPrinting" value="true"/>
  <param name="SyslogHost" value="localhost"/>
  <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="[%d{ABSOLUTE},%c{1}] %m%n"/>
  </layout>
</appender>
</source>

* '''SyslogHost''': This configuration parameters allows you to specify the local syslog or a remote syslog server used to centralize the network log management.

For more info, visit:

* http://jboss.org/community/docs/DOC-11280
* http://jboss.org/community/docs/DOC-9372
* http://jakarta.apache.org/log4j
* http://primalcortex.wordpress.com/2007/11/28/jboss-and-jaas-debug
* [http://stackoverflow.com/questions/1050256/how-can-i-get-log4j-to-delete-old-rotating-log-files|How can I get log4j to delete old rotating log files?]

[[Category: Installation Guide]]
[[Category: Developer Guide]]