Configuration: Frequently Asked Questions

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

How has configuration changed with the version 3 platform changes?

Version 3 introduced big changes by creating a platform on which application instances are deployed. In particular, the jiveHome directory was replaced with the jive.instance.home environment variable.

Fundamentally, each instance depends on three environment variables to identify its place in the bigger picture of its environment:

• jive.home - The root of all Jive software on the filesystem. Shared resources like Apache and Tomcat binaries are found here, as are individual instances.
• jive.instance.home - Where a given instance stores all of its working files (previously jiveHome).
• jive.name - Unique, human-readable identifier of an instance within the local deployment (and importantly, not across all deployments); this value influences where the instance lives in a managed deployment (i.e., platform) and various other subtle artifacts like log file names.

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

• jive.instance.home  -- This is where the application puts working files, including caches, plugins, themes, etc. For example, by default this would be /usr/local/jive/applications/sbs/home/.
  
• 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?

• /usr/local/jive/applications/sbs/home/jive_startup.xml - Defines your database connection and provider.
• The rest of the key configurations will happen in the admin console.

How do I set my jive.instance.home?

• Jive SBS uses the following convention to determine where jive.instance.home actually exists on the file system. These rules follow the general notion of more to less specific -- for example, if a user has gone to the trouble of specifying a JNDI property for the home directory, honor that over a more generic system property, honor that over a more generic environment property.

In summary, worst case, your jive.instance.home will default to "/usr/local/jive/applications/sbs/home" on *nix or "c:\jive\applications\sbs\home" on Windows. This might actually work for Windows users, but certainly shouldn't work for *nix users who won't have write to /usr/local unless you're running as root and nobody's doing that, right?

• The jive_init.xml file is no longer used by the application.

• Deploying multiple application instances to the same Tomcat instance is not supported on the SBS platform.
  
• JNDI values can be configured in Tomcat a number of ways, depending on how you are running Tomcat. For example, you can hard code a context into your Tomcat environment so your server.xml looks like this:

<Context path="${jive.context}"
    antiJARLocking="true" antiResourceLocking="true"
    docBase="${jive.application}"
    workDir="${jive.work}"
    reloadable="false" unpackWAR="false"
    cacheTTL="${jive.app.cache.ttl}" cacheMaxSize="${jive.app.cache.size}" cachingAllowed="true"
    swallowOutput="true">
    <Environment name="jive.instance.home" value="${jive.instance.home}" type="java.lang.String"/>
</Context>

In the snippet above, all dollar-bracket values are substituted at run time with system property values making this effectively the same as setting the -D parameter.

Legacy usages of jiveHome in system properties and JNDI are still supported but should not be used in new development and will result in a warning at startup.

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 the app 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 jive.instance.home for a deployment?

rm -f <jive.instance.home>/jive_startup.xml
rm -f <jive.instance.home>/jive.license
rm -f <jive.instance.home>/attachments/*.bin
rm -f <jive.instance.home>/attachments/*.txt
rm -f <jive.instance.home>/attachments/cache/*
rm -f <jive.instance.home>/images/*.bin
rm -f <jive.instance.home>/images/cache/*
rm -f <jive.instance.home>/documents/*
rm -f <jive.instance.home>/documents/cache/*
rm -f /usr/local/jive/var/logs/*
rm -rf <jive.instance.home>/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 file system. You should use the file system whenever possible. You'll find log output in /usr/local/jive/var/logs.

By default the logging threshold is set to INFO. You can change the 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.instance.home>/etc. You will want to do this on a temporary basis. Here is an example file, updated for version 2.5.3. To be sure you have the appropriate file, copy the source file log4-file.properties to <jive.instance.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=${jive.logs}/${jive.name}-container.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=${jive.logs}/${jive.name}-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=${jive.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 two 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 /usr/local/jive/var/logs/sso.log

Can I set some proxool debug settings?

In version 2.0, you can 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>