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.
    1. JNDI environment property named "jive.instance.home" in the context "java:comp/env/"
    2. System property named "jive.instance.home"
    3. JNDI legacy environment property named "jiveHome" in the same context as #1
    4. System property named "jiveHome"
    5. Default to OS default (/usr/local/jive/applications/${name}/home or c:\jive\applications\${name}\home} - ${name} is described above represents the -Djive.name property with a default of "sbs"

    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.example=DEBUG, SSOFILE
    log4j.additivity.com.jivesoftware.example=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>
    

     

    One important thing to note: log4j.logger.org.logicalcobwebs will need to be set to DEBUG in your log4j files for this to work.

    Is it  possible to modify the AD settings after an instance is configured?

    If you want to change the configuration options you can either modify  the system properties (anything that starts with ldap.*) or  re-enter setup by modifying the jive_startup.xml file. Either  way, you'll wind up restarting because almost all of those system  properties require a restart to take effect. And if you need to change  the admin DN and/or admin DN password, you'll need to go through setup  because it is the only way that it will be encrypted.