Configuration: Frequently Asked Questions

This FAQ provides information on common tasks related to configuring the application, from logging to startup to clustering and more.

What are some of the most important configurations I need to be concerned with?

• jiveHome  - This is where Clearspace puts many, many things: caches, logs, plugins, themes, etc. The best place to put this is in an environment variable.
  
• jiveURL - This is the hostname and path of your application. This gets inserted into all links rendered in the app using the <@s.url> tag.  This can be set as a persistent jiveProperty in the Admin console.

What are the key configuration files I need to be concerned with?

• /<jive_home>/jive_startup.xml - Defines your database connection, provider and log levels
• The rest of the key configurations will happen in the Admin Console.

How do I set my jiveHome?

• The best way to accomplish this is to set an environment variable for tomcat, the equivalent of  JAVA_OPTS="-DjiveHome=<OS-specific path to jive home>" The way you set that varries from platform to platform but generally if you put a setenv.sh/bat in $CATALINA_HOME/bin/ - tomcat will read the value.
• Explicitly setting the environment variable does not depend on the WAR or app server behavior.
• Using jive_init.xml is considered deprecated.  You can go to jive_init.xml file under /webapps/clearspace_community/WEB-INF/classes. Manually set your jiveHome value to be the location of your jiveHome from the old instance.  However, to hack jive_init.xml, you have to:
  • Explode the WAR, find the file, edit prior to deploying or
  • Depending on the app server, find the exploded WAR and hack what is effectively a temp file laid down by the app server that you were never meant to touch by the vendor
  • Neither of the above is any good when you upgrade. In some app servers, when you undeploy a WAR file it deletes those temp files including your jive_init.xml. If you've modified the original WAR (shudder), you've just undeployed your jive_init.xml during an upgrade and you have to remember to edit the new WAR before you deploy it.  Re-running setup in absence of a jive_init.xml, with an un-upgraded setup is almost certain to break. We don't test that way at all and it would really shackle what we can do in setup.
• If you're deploying multiple CS instances in the same container, you can use JNDI lookups for Jive home, so each deployment can have its own jive home set in the deployment context.

Why would I want to change <setup> to false in my jive_startup.xml?

The <setup> element is where the application stores its state of whether it's run through setup or not.  It should only be set to false when you have a new installation.  Once you've configured CS it should be set to true.  If you set <setup> to “false” this will cause you to go into setup. You should not need to do this for a new instance. The app should connect to the db and detect that it needs to perform an upgrade. The only time you will want to re-run setup is to change the LDAP configuration settings and mappings.

How do I clean up a jiveHome for a deployment?

rm -f jiveHome/jive_startup.xml
rm -f jiveHome/jive.license
rm -f jiveHome/attachments/*.bin
rm -f jiveHome/attachments/*.txt
rm -f jiveHome/attachments/cache/*
rm -f jiveHome/images/*.bin
rm -f jiveHome/images/cache/*
rm -f jiveHome/documents/*
rm -f jiveHome/documents/cache/*
rm -f jiveHome/logs/*
rm -rf jiveHome/search/*

How do I change my logging levels?

The preferred method of logging is to use log4j.  Jive provides two methods of getting at logs, one from the Admin Console, and another from the filesystem.  You should prefer to use the filesystem whenever possible.  The logs are output in <JIVE_HOME>/logs/

By default the logging threshold is set to INFO.  You can change the Logging Threshold in the Admin Console in the page System > Management > Log Viewer.   However, whether or not this will result in your getting the output you need depends on how you've configured the base logger. To change that to the lowest levels you'll need to override the default settings.

You can override default settings by creating a new log4j.properties file in JIVE_HOME/etc  You will want to do this on a temporary basis.  Here is an example file, updated for Clearspace 2.5.3.  To be sure you have the appropriate file, copy the source file log4-file.properties to JIVE_HOME/etc and rename it log4j.properties, and modify it to suit your needs.

Here is the current log4j.properties file you can use, unmodified.

# Set root category priority to DEBUG and set the appenders to CONSOLE, LOGFILE and LOGEVENT
log4j.rootCategory=DEBUG, CONSOLE, LOGFILE

# CONSOLE is set to be a ConsoleAppender using a PatternLayout.
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.Threshold=INFO
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%d{ABSOLUTE} [%t] %p %c - %m%n

# LOGFILE is set to be a File appender using a PatternLayout.
log4j.appender.LOGFILE=org.apache.log4j.RollingFileAppender
log4j.appender.LOGFILE.File=${jiveHome}/logs/clearspace.log
log4j.appender.LOGFILE.MaxBackupIndex=10
log4j.appender.LOGFILE.MaxFileSize=100MB
log4j.appender.LOGFILE.Append=true
log4j.appender.LOGFILE.Threshold=INFO
log4j.appender.LOGFILE.BufferedIO=true
log4j.appender.LOGFILE.BufferSize=1024
log4j.appender.LOGFILE.layout=org.apache.log4j.PatternLayout
log4j.appender.LOGFILE.layout.ConversionPattern=%d{DATE} [%t] %p %c{2} - %m%n

# SESSIONFILE is set to be a File appender using a PatternLayout.
log4j.appender.SESSIONFILE=org.apache.log4j.RollingFileAppender
log4j.appender.SESSIONFILE.File=${jiveHome}/logs/session.log
log4j.appender.SESSIONFILE.MaxBackupIndex=10
log4j.appender.SESSIONFILE.MaxFileSize=100MB
log4j.appender.SESSIONFILE.Append=true
log4j.appender.SESSIONFILE.Threshold=INFO
log4j.appender.SESSIONFILE.BufferedIO=false
log4j.appender.SESSIONFILE.BufferSize=1024
log4j.appender.SESSIONFILE.layout=org.apache.log4j.PatternLayout
log4j.appender.SESSIONFILE.layout.ConversionPattern=%d{DATE} [%t] %p - %m%n

# Define Individual Package Logging Levels
log4j.logger.org.springframework=WARN
log4j.logger.org.logicalcobwebs=ERROR
log4j.logger.org.apache.struts2=WARN
log4j.logger.org.apache.cxf=WARN
log4j.logger.org.directwebremoting=WARN
log4j.logger.com.opensymphony=WARN

# Target session data to the SESSIONFILE and SESSIONFILE only
log4j.logger.com.jivesoftware.community.aaa.AuthSessionListener=INFO, SESSIONFILE
log4j.additivity.com.jivesoftware.community.aaa.AuthSessionListener=false
log4j.logger.com.jivesoftware.community.action.LogoutAction=INFO, SESSIONFILE
log4j.additivity.com.jivesoftware.community.action.LogoutAction=false
log4j.logger.com.jivesoftware.community.aaa.SessionTrackingFilter=INFO, SESSIONFILE
log4j.additivity.com.jivesoftware.community.aaa.SessionTrackingFilter=false

# Log jive messages at INFO
log4j.logger.com.jivesoftware=INFO

Here is an example where you can create a new file for just the code you're interested in:

# SSOFILE is set to be a File appender using a PatternLayout.
log4j.appender.SSOFILE=org.apache.log4j.RollingFileAppender
log4j.appender.SSOFILE.File=${jiveHome}/logs/sso.log
log4j.appender.SSOFILE.MaxBackupIndex=10
log4j.appender.SSOFILE.MaxFileSize=100MB
log4j.appender.SSOFILE.Append=true
log4j.appender.SSOFILE.Threshold=DEBUG
log4j.appender.SSOFILE.BufferedIO=false
log4j.appender.SSOFILE.BufferSize=1024
log4j.appender.SSOFILE.layout=org.apache.log4j.PatternLayout
log4j.appender.SSOFILE.layout.ConversionPattern=%d{DATE} [%t] %p %c{2} - %m%n

Then set the logging for those files only:

# SSO DEBUG
log4j.logger.com.jivesoftware.plugins.sitemindersso=DEBUG, SSOFILE
log4j.additivity.com.jivesoftware.plugins.sitemindersso=false
log4j.logger.com.jivesoftware.brocade=DEBUG, SSOFILE
log4j.additivity.com.jivesoftware.brocade=false
log4j.logger.com.jivesoftware.plugins.aaa=DEBUG, SSOFILE
log4j.additivity.com.jivesoftware.plugins.aaa=false

You need 2 statements per package, the logger key and the additivity key.

That's it.  From now on your debugging statements go into the new file you've created in jiveHome/logs/sso.log

Can I disable clustering in jive_init.xml?

<cache>
  <clustering>
     <enabled>false</enabled>
   </clustering>
    <Short-termQuery></Short>
</cache>

Can I set some proxool debug settings?

In 2.0, we allow you to set a subset of Proxool properties ( http://proxool.sourceforge.net/properties.html ) in jive_startup.xml

This set can be expanded as necessary.

Currently, the properties supported are:

• connectionProvider.proxool.trace
• connectionProvider.proxool.verbose
• connectionProvider.proxool.statistics
• connectionProvider.proxool.statisticsLogLevel
• connectionProvider.proxool.jmx
• connectionProvider.proxool.jmxAgentId

In the XML it will look something like:

<jive>
 ...
<connectionProvider>
     ...
     <proxool>
       <trace>true</trace>
        <verbose>true</verbose>
        <statistics>1m,5m,15m</statistics>
        <statisticsLogLevel>DEBUG</statisticsLogLevel>
     </proxool>
 ...
</connectionProvider>
 ...
</jive>