Jetspeed

Essentials

Download

Documentation

Components

Get Involved
Status of this document

This document is very much a "Work in Progress". Although some sections are incomplete, I hope what is here is helpful. Comments and suggestions are welcome and encouraged. They can be set to jetspeed-user@jakarta.apache.org


General Configuration steps

The following steps are purely guide. Some steps are not required.


Override any properties in default property files (jr.props, tr.props, Torque.props)

Any site specific property settings may be placed in a custom property file (see /WEB-INF/conf/my.properties for an example). Using a custom property file makes future Jetspeed upgrades easier because the default property files remain unchanged. The following steps are required to activate such custom property file

See the Portlet Catalog for portlet configuration documentation.


Define portlets in local-portlets

Any site specific portlets should be define in <jetspeed_home>/WEB-INF/conf/local-portlets.xreg. because this file will not be overwritten by upgrades.

See the Portlet Catalog for portlet configuration documentation.


Define skins in local-skins.xreg

Any site specific skins should be define in <jetspeed_home>/WEB-INF/conf/local-skins.xreg. because this file will not be overwritten by upgrades.

See the Skin configuration guide for more information.


Define local controls and controllers in local-managers.xreg

Any site specific controls and controllers should be define in <jetspeed_home>/WEB-INF/conf/local-managers.xreg. because this file will not be overwritten by upgrades.


Define content feeds

This section is incomplete


Configure the layout and navigation bars

This section is incomplete

The look of Jetspeed's portal is controlled by the layout and navigation templates. Below are some of the file that define that look.

A Layout Manager is used in the generation of the resulting portal. Jetspeed support 2 Layout Manager, JSP and Velocity. Both layout manager produce the similar results, which one you use is dictated by which language you prefer.

The parameter services.TemplateService.default.extension in TurbineResource.properties defines the Layout manager used.

Value Description
jsp The JSP layout manager will be used. This is the 1.3a1 default
vm The vm layout manager will be used. This is the 1.3a2, 1.4b1, 1.4b2 default

Files uses by the Velocity Layout Manager
<jetspeed_home>/WEB-INF/template/vm/layouts/html/language/country/default.vm
Display the logo in the upper left hand corner and the define the top, bottom, and left navigation bars.
<jetspeed_home>/WEB-INF/template/vm/navigations/html/language/country/top.vm
Top navigation bar when the user it NOT logged in.
<jetspeed_home>/WEB-INF/template/vm/navigations/html/language/country/left.vm
Left navigation bar for all users.
<jetspeed_home>/WEB-INF/template/vm/navigations/html/language/country/bottom.vm
Bottom navigation bar for all users.

Files uses by the JSP Layout Manager
<jetspeed_home>/WEB-INF/template/jsp/layouts/html/language/country/default.jsp
Display the logo in the upper left hand corner and the define the top, bottom, and left navigation bars.
<jetspeed_home>/WEB-INF/template/jsp/navigations/html/language/country/top_default.jsp
Top navigation bar when the user is NOT logged in.
<jetspeed_home>/WEB-INF/template/jsp/navigations/html/language/country/top_loggedin.jsp
Top navigation bar for logged in users.
<jetspeed_home>/WEB-INF/template/jsp/navigations/html/language/country/left.jsp
Left navigation bar for all users.
<jetspeed_home>/WEB-INF/template/jsp/navigations/html/language/country/bottom/jsp
Bottom navigation bar for all users.

To customize the navigation bars, the following steps are suggested:

  • Replace the reference to the Jetspeed logo with your logo in default.xx
  • Add "banner adds" to top.vm or top_default.jsp and top_loggedin.jsp
  • If no left navigation bar is desired, them remove the referance from default.xx
  • If a left navigation bar is desired, then update left.xx
  • Add any copyright notices, disclaimers, logos, ... to bottom.xx


Configure default home page

This section is incomplete

The default home page is stored in the <jetspeed_home>/WEB-INF/psml/anon directory. Currently this is not directly configurable with the customizer. A suggested procedure is to create a HomePageUser, do the desired configuration as that user, then copy the resulting files to the default home page.


Define users

This section is incomplete


Configure the admin and turbine users

This section is incomplete

Change the passwords!


Define default portal for new users

A new users home page is copied from the user TURBINE. Thus you should customized the TURBINE's user home page to reflect the desired default home page for new users.


Set portlet caching and other refresh rates

This section is incomplete


Set Jetspeed logging

Jetspeed utilizes the logging services provided by Turbine. The logfile(s) are a valuable tool in trouble shooting problems and monitoring the general health of Jetspeed an it's portlets.

The logging level should be set according the the current needs. DEBUG logging is suggested during portlet testing, while INFO logging is appropriate for every-day activity in a stable environment.

Not all of Turbine's logging services are included. Additional documentation can be found at http://jakarta.apache.org/turbine.

Facility Description
rotation Rotation of log files. This will limit the amount of disk space consumed by the log file. Not supported by all loggers. To enable this logger, you must replace "logforj" with "rotation" on the facilities list and set default logger to "rotation". Please check log4j documentation for information on various appenders that can be used here (i.e. RollingFileAppender vs. DailyRollingFileAppender).
debug This logger sends log messages to both console and log file. It is useful for testing and debugging but is not appropriate for production use. To enable this logger, you must add "debug" to the facilities list and set default logger to "debug".
schedule A facility for the scheduler service To disable started/stopped messages set the level to ERROR
security A facility for security audit. NOTE! As of 23 Jan 2001 Turbine does not have any standard security auditing functionality. It's up to your application.
system A facility for system logging.
sql A facility for SQL query logging To enable SQL query logging, set the level to DEBUG

FileLogger

This is a logging service provide with Turbine.

Additional information can be found at http://jakarta.apache.org/turbine

Facility Description
destination.file Name of the log file relative to <jetspeed-home>
className org.apache.turbine.services.logging.FileLogger
level
Value Description
ERROR Designates error events that might still allow the application to continue running
WARN Designates potentially harmful situations
INFO Designates informational messages that highlight the progress of the application at course-grained level.
DEBUG Designates fine-grained informational events that are most useful to debug an application
destination.console Optional, default = false
Value Description
false message will NOT be sent to the console
true message will ALSO be sent to the console
   

Log4JavaLoggger

This is a more functional logging service that can interact with operating specific facilities like UNIX's syslog and Window's Event Logger

Additional information can be found at http://jakarta.apache.org/log4j and http://jakarta.apache.org/turbine

Configuration notes:

  • All loggers define in services.LoggingService.facilities must be the same type when using the Log4J services.
  • When using log file rotation, the rotation facility must be the first in the services.LoggingService.facilities list and should replace the logforj facility.

Facility Description
destination.file Name of the log file relative to <jetspeed-home>
className org.apache.turbine.services.logging.Log4JavaLogger
level
Value Description
FATAL Designates very severe error events that will presumably lead the application to abort.
ERROR Designates error events that might still allow the application to continue running
WARN Designates potentially harmful situations
INFO Designates informational messages that highlight the progress of the application at coarse-grained level.
DEBUG Designates fine-grained informational events that are most useful to debug an application
MaxFileSize Approximate log file size in bytes. 1MB = 1048576 bytes
MaxBackupIndex Number of backup log files to maintain. The actual number of log files will be file.backups + 1.

Portlet usage logger

This facility is useful to generate web server like access log which captures access to individual portlets (since this cannot be accomplished via regular web server logging). See javadoc for org.apache.jetspeed.services.JetspeedPortletStatsService for more information about the internals of this service. The following are service properties as defined in JetspeedResources.properties:

Property Description
services.PortletStats.classname = org.apache.jetspeed.services.portletstats.JetspeedPortletStatsService Simple implementation using Apache Common Log Format (CLF)
services.PortletStats.logger = access Name of the log4j logger
services.PortletStats.enabled = false This service is disabled by default
services.PortletStats.excludePortlets = Portlets to exclude from logging (not yet implemented)
services.PortletStats.dateFormat = dd/MMM/yyyy:hh:mm:ss z Date format to use in the log entry

Example configuration

The following configuration will rotate the logging among 6 files. All logging will be at the DEBUG level. 

# -------------------------------------------------------------------
# 
#  L O G S
#
# -------------------------------------------------------------------
# This is the configuration for the logging system. In most cases
# you don't need to modify anything. However, if you wish to add more
# facilities or modify the existing settings, then you can do so.
#
# destination.file: A path relative to the web app root
# -------------------------------------------------------------------
services.LoggingService.facilities=logforj,access
services.LoggingService.default=logforj
services.LoggingService.loggingConfig=org.apache.turbine.services.logging.PropertiesLoggingConfig

# A facility for system logging.
services.LoggingService.system.destination.file=/WEB-INF/log/jetspeed.log
services.LoggingService.system.className=org.apache.turbine.services.logging.FileLogger
services.LoggingService.system.level=DEBUG

# A facility for the scheduler service
# To disable started/stopped messages set the level to ERROR
services.LoggingService.scheduler.destination.file=/WEB-INF/log/jetspeed.log
services.LoggingService.scheduler.className=org.apache.turbine.services.logging.FileLogger
services.LoggingService.scheduler.level=DEBUG

# A facility for debugging applications. Messages will go both
# to the log file and the server console.
services.LoggingService.debug.destination.file=/WEB-INF/log/jetspeed.log
services.LoggingService.debug.destination.console=true
services.LoggingService.debug.className=org.apache.turbine.services.logging.FileLogger
services.LoggingService.debug.level=DEBUG

# A facility for SQL query logging
# To enable SQL query logging, set the level to DEBUG
services.LoggingService.sql.destination.file=/WEB-INF/log/jetspeed.log
services.LoggingService.sql.className=org.apache.turbine.services.logging.FileLogger
services.LoggingService.sql.level=DEBUG

# A facility for security audit. NOTE! As of 23 Jan 2001
# Turbine does not have any standard security auditing
# functionality. It's up to your application.
services.LoggingService.security.destination.file=/WEB-INF/log/jetspeed.log
services.LoggingService.security.className=org.apache.turbine.services.logging.FileLogger
services.LoggingService.security.level=DEBUG

# An example configuration for using Log4Java, with log4j properties inline
# The category name - at the end of this line - needs to match the logging facility name - the first log4j.
# need this rootCategory entry to capture the torque/fulcrum etc logging
services.LoggingService.logforj.log4j.rootCategory = INFO, logforj

# need this category entry for the actual jetspeed logging (I don't know why it doesn't get covered by the root category!)
services.LoggingService.logforj.log4j.category.logforj = DEBUG, logforj

services.LoggingService.logforj.log4j.appender.logforj.file =${webappRoot}/WEB-INF/log/jetspeed.log
services.LoggingService.logforj.log4j.appender.logforj = org.apache.log4j.FileAppender
services.LoggingService.logforj.log4j.appender.logforj.layout = org.apache.log4j.PatternLayout
services.LoggingService.logforj.log4j.appender.logforj.layout.conversionPattern = [%d{dd MMM yyyy HH:mm:ss} %5p] - %m%n
services.LoggingService.logforj.log4j.appender.logforj.append = false
services.LoggingService.logforj.className=org.apache.turbine.services.logging.Log4JavaLogger
services.LoggingService.logforj.level=DEBUG

# An example configuration for portlet access audit logging
services.LoggingService.access.log4j.category.access = INFO, access
services.LoggingService.access.log4j.appender.access = org.apache.log4j.FileAppender
services.LoggingService.access.log4j.appender.access.layout = org.apache.log4j.PatternLayout
services.LoggingService.access.log4j.appender.access.layout.ConversionPattern = %m%n
services.LoggingService.access.log4j.appender.access.append = true
services.LoggingService.access.log4j.appender.access.file = ${webappRoot}/WEB-INF/log/access.log
services.LoggingService.access.className = org.apache.turbine.services.logging.Log4JavaLogger
services.LoggingService.access.level = INFO

# An example configuration for automatic log rotation using Log4Java
# This will keep the log file size under 1MB and save up to 5 backup copies
services.LoggingService.rotation.log4j.rootCategory = INFO, rotation
services.LoggingService.rotation.log4j.category.rotation = DEBUG, rotation

services.LoggingService.rotation.log4j.appender.rotation.file = ${webappRoot}/WEB-INF/log/jetspeed.log
services.LoggingService.rotation.log4j.appender.rotation = org.apache.log4j.RollingFileAppender
services.LoggingService.rotation.log4j.appender.rotation.layout = org.apache.log4j.PatternLayout
services.LoggingService.rotation.log4j.appender.rotation.layout.conversionPattern = [%d{dd MMM yyyy HH:mm:ss} %5p] - %m%n
services.LoggingService.rotation.log4j.appender.rotation.append = false
services.LoggingService.rotation.log4j.appender.rotation.MaxFileSize = 1024KB
services.LoggingService.rotation.log4j.appender.rotation.MaxBackupIndex = 5
services.LoggingService.rotation.className = org.apache.turbine.services.logging.Log4JavaLogger
services.LoggingService.rotation.level = DEBUG

# An example configuration for using *NIX syslogd with Log4Java
services.LoggingService.syslog.destination.syslogd.host=my.syslog.server.com
services.LoggingService.syslog.destination.syslogd.facility=LOG_DAEMON
services.LoggingService.syslog.className=org.apache.turbine.services.logging.Log4JavaLogger
services.LoggingService.syslog.level=INFO

# An example configuration for using remote Log4Java server
services.LoggingService.remote.destination.remote.host=my.remote.server.com
services.LoggingService.remote.destination.remote.port=1099
services.LoggingService.remote.className=org.apache.turbine.services.logging.Log4JavaLogger
services.LoggingService.remote.level=INFO

# An example configuration for sending error reports as email with Log4Java
# notes:
# * uses 'mail.server' as SMTP server to send mail through
# * log4j will send the email when an ERROR is logged, with
#   'buffer.size' previous (non-ERROR) logs included in the email
# * configured to log to a file as well otherwise stacktraces are lost
services.LoggingService.email.destination.file=/WEB-INF/log/jetspeed.log
services.LoggingService.email.destination.email.from=root@localhost
services.LoggingService.email.destination.email.to=root@localhost
services.LoggingService.email.destination.email.subject=Jetspeed Error Report
services.LoggingService.email.destination.email.buffer.size=512
services.LoggingService.email.className=org.apache.turbine.services.logging.Log4JavaLogger
services.LoggingService.email.level=INFO


Enable e-mail confirmation

This section is incomplete


Logon Configuration
Case Insensitive Logon

Jetspeed can be configured to automatically force all usernames and passwords to upper or lower case. By setting the "caseinsensitive" property for the username or password to "true", then the "caseinsensitive.upper" property can be applied. When it is true, the username or password is converted to uppercase. When false, username or password are converted to lowercase. The default setting is false, where the username and password will be case-sensitive and the "caseinsensitive.upper" property is ignored.

services.JetspeedSecurity.caseinsensitive.username=false
services.JetspeedSecurity.caseinsensitive.password=false
services.JetspeedSecurity.caseinsensitive.upper=true

Logon Rules

When a new user is created, the PSML resources for the new user are copied from another user's account. This account is configurable with the property:

services.Profiler.newuser.template=turbine

Setting it to nothing configures role-based psml as the default method for new users.

services.Profiler.newuser.template=

Role Based PSML

Some configuration will want to share PSML resources among users. In this case, users will not have their own PSML resources. Enable Role Based PSML with this property set to true:

services.Profiler.rolefallback=true

Remember to set the "services.Profiler.newuser.template" property to nothing.

In other configurations, it may be useful to create inital user PSML based on the roles the user is a assigned. The role profile merging feature aggregates PSML from each role to create a single tabbed profile. To enable this feature the following settings have to be set to true:

services.Profiler.rolefallback=true
services.Profiler.rolemerge=true

Assigning Roles, Media Type

When a new user is created, you can configure which roles are automatically signed to that new user. You may also configure which media types that new user will support. Use commas to separate multiple entries.

services.JetspeedSecurity.newuser.roles=user
services.Profiler.newuser.media_types=html,wml


Account Disabling

Accounts can be auto-disabled with a failed-logon tracking feature. To turn on this feature, set this property:

services.JetspeedSecurity.logon.auto.disable=true

Account Disabling is controlled by the parameters: count, interval, and max. These parameters are applied over the lifetime of the server. When the server is shutdown, all counts are reset. However, the 'disabled' status is persisted in the database. With the parameters below, the user is given 3 failed attempts over 300 seconds (5 minutes). After 5 minutes or a successful logon, the strike count is reset. After 3 failed attempts within 5 minutes, the account is disabled and the Over the entire run of the server, and the "logon.disabled.form" is displayed whenever the user attempts to logon again. The 'max' parameter counts all failed logon attempts over the entire lifetime of the server. After 10 failed attempts over the lifetime of the server, the account is disabled. Accounts can be enabled from the Jetspeed Admin User Maintenance screen.

# 3 logon strikes per 300 seconds and your out
services.JetspeedSecurity.logon.strike.count=3
services.JetspeedSecurity.logon.strike.interval=300
# dont allow more than 10 over any time period
services.JetspeedSecurity.logon.strike.max=10
logon.disabled.form=AccountDisabled.vm


Automatic Password Expiration

Password can automatically expire with this feature. When password expires, the user is presented with a a change password screen. The user must change the password in order to continue. When new user is created, a temporary password is assigned. On first login, the user is then prompted to change the password. The administrator can force password expiration by setting column PASSWORD_CHANGED to null in TURBINE_USER for particular account(s). To turn on this feature, set this property to a value greater than 0:

services.JetspeedSecurity.password.expiration.period=[number of days before the password expires]


Backup and Test

This section is incomplete

Backup early and often!


Copyright © 1999-2002, Apache Software Foundation