Configuring J2EE Containers for SESM Applications

J2EE Containers

Container Requirement for the Port-Bundle Host Key Feature

Creating WAR Files for Containers Other Than Jetty

Jetty Container MBeans

Log MBean

Debug MBean

Server MBean

SESMSocketListener MBean

SESMSSLListener MBean

Configuring J2EE Containers for SESM Applications

The SESM installation process performs all required configurations for running the SESM applications in Jetty containers. Use this chapter if you want to change or fine-tune the J2EE container configuration after installation. This chapter contains the following topics:

J2EE Containers

SESM portals and CDAT are J2EE web applications. They must run in a J2EE web server. The web server is the container for the applications that run in it. The SESM installation program installs and configures Jetty servers as the containers for the SESM portal applications and CDAT. Deployers can create a web archive (WAR) file from the installation and deploy SESM applications in other containers.

Container Requirement for the Port-Bundle Host Key Feature

Before you deploy SESM applications in containers other than Jetty, determine if your solution requires the port-bundle host key feature on the Service Selection Gateway (SSG). For solutions that use SSG, we recommend enabling the port-bundle host key feature.

Note The Jetty server is currently the only J2EE-compliant server that can support the port-bundle host key feature.

The port-bundle host key feature uses a software token (or key) that uniquely identifies each subscriber on the host SSG that is currently logged on to an SESM portal, even when multiple subscribers are using the same IP address. The port-bundle host key feature also provides an SSG IP address in the key.

The port-bundle host key feature provides the following advantages to SESM portal applications:

It allows SESM portal applications to robustly handle overlapping IP addresses, nonroutable IP addresses, and dynamically assigned IP addresses.
It eliminates the need to explicitly map subscriber subnets to SSGs.

When port-bundle host key is enabled on the SSG, the SSG preserves the port number of the incoming HTTP request. This remote port number becomes the key that uniquely identifies each subscriber. The key is included in the request that is forwarded to the SESM web application.

The SSG makes the port number available, but the J2EE server must access this information and pass it along to the SESM web application. To do this, the Jetty server uses the PortBundleHandler, an extension that allows access to the request handling part of the server API and thus get the remote port number.

The PortBundleHandler is added to the Jetty container by the following file under the SESM application directory (nwsp, for example):

nwsp

webapp

WEB-INF
   web-jetty.xml

Jetty version 4.1.0RC6 is bundled with SESM Release 3.1(7). This Jetty version adds the contents of web-jetty.xml. In Jetty versions earlier than Version 4, the port bundle handler must be added in the nwsp.jetty.xml file.

Creating WAR Files for Containers Other Than Jetty

You can create web archive (WAR) files to use in deploying the sample SESM applications in non-Jetty web containers. To create a WAR file, use the jar command on the webapps directory under the desired SESM application. For example, to create a WAR file for NWSP on a Solaris system, enter the following commands:

cd installDir/nwsp/webapp
jar cf0 ../nwsp.war *

For instructions about deploying an application using a WAR file, see the documentation for the container you are using.

The installed configuration is specific to a Jetty container. If you choose to deploy the SESM applications in a container other than Jetty, you must make changes to the container MBeans. For example, you must change class or object names. You might need to add MBeans.

Jetty Container MBeans

A Jetty container uses the following MBeans:

To change attributes in these MBeans, you can use either of the following methods:

Edit the container's MBean configuration file:

jetty
   config
      nwsp.jetty.xml
      wap.jetty.xml
      pda.jetty.xml
      cdat.jetty.xml

Make changes using the Agent View running on the application's management port. For example, the Agent View for the NWSP application provides access to both the application and the container MBeans.

Note Containers do not have their own management consoles.

Log MBean

The Log MBean enables the Jetty server debugging and logging mechanisms and configures the information that appears in the jetty log file. Table 4-1 describes the attributes in the Log MBean.

Table 4-1: Jetty Container—Log MBean

Attribute Name	Explanation
logTimezone	Installed default: empty
logDateFormat	Controls the format of the date stamp in the log messages. Installed default: yyyyMMdd:HHmmss.SSS
logLabels	Controls whether or not the log messages include frame details. Installed default: false
logOneLine	Installed default: false
logStackSize	Controls whether or not the log messages include an indication of stack depth. Installed default: false
logStackTrace	Controls whether or not the log messages include trace information. Installed default: false
logTags	Installed default: true
logTimeStamps	Installed default: true
append	Indicates if messages overwrite existing contents (false) or are appended to the existing file (true). Installed default: true
retainDays	Indicates the number of days to keep an old log file before deleting it. Installed default: 31
filename	Specifies the log filename and path, as follows: application.home/logs/yyyy_mm_dd.jetty.log Where: application.home—A property whose value is set in the SESM start script. See Table 9-1. logs—A constant. All log files appear in the logs subdirectory under the application directory. yyyy_mm_dd—The year, month, and day that the file was created. .jetty.log—A constant identifying the Jetty log files.

Debug MBean

The Debug MBean enables or disables the Jetty server debugging mechanism. Table 4-2 describes the attributes in the DebugMBean.

Table 4-2: Jetty Container—Debug MBean

Attribute Name	Explanation
debug	Controls whether or not debugging messages are produced. Installed default: false
debugPatterns	By specifying one or more patterns, you turn on a filtering mechanism that excludes any message that does not match the pattern. The patterns are file, class, or method names. Pattern matching is based on substring matches. For example, if you specify the pattern RADIUS, the software focuses on RADIUS messages. To specify multiple patterns, separate the patterns using a comma. Installed default: empty
verbose	Specifies the level of detail reported in debugging messages. The range of allowed values is 0 (no details) to 255 (all details). Installed default: 0
suppressStack	Controls whether or not stack information is included in debug messages. Installed default: false
suppressWarnings	Controls whether or not warning messages are included in debug messages. Installed default: false

Server MBean

The Server MBean configures a request log, which records all incoming HTTP requests. Table 4-3 describes the attributes in the Server MBean.

Table 4-3: Jetty Container—Server MBean

Attribute Name	Explanation
RequestLog	Creates a new class with one argument, which specifies the name and location of the request log. The installed value is: application.home/logs/yyyy_mm_dd.request.log Where: application.home—A property whose value is set in the SESM start script. See Table 9-1. logs—A constant. All log files appear in the logs subdirectory under the application directory. yyyy_mm_dd—The year, month, and day that the file was created. The installation program uses the appropriate path name delimiter for the installation platform. .request.log—A constant identifying an HTTP request file.
retainDays	Indicates the number of days to keep a log file before deleting it. Installed default: 90
append	Indicates whether or not to append messages to an existing file or to create a new file for each application instance. Installed default: true
<Call addWebApplication>	This call adds the SESM application to run on the web server. It uses five positional arguments: 1. The first positional argument specifies the virtual host name for the web server application. 2. The second positional argument specifies the context path for locating the web server application. For example, / or /pathname/. 3. The third positional argument identifies the location of the application. The value is: application.home/webapp Where application.home* is a system property whose value is set in the start script. 4. The fourth positional argument identifies the location of the webdefault.xml file for this application. The value is: jetty.home/config/webdefault.xml Where jetty.home is a system property whose value is set in the start script. 5. The fifth positional argument specifies whether or not web archive (WAR) files are used. Valid values are TRUE and FALSE. The first three arguments define the location of the web server application. `host/context/application` The SESM start script derives the values for application.home and jetty.home from an expected (installed) directory structure. To change these values, edit the start script.

SESMSocketListener MBean

The SESMSocketListener MBean configures the port that the Jetty server listens on for HTTP requests from subscribers. Table 4-4 describes the attributes in the SESMSocketListener MBean.

Table 4-4: Jetty Container—SESMSocketListener MBean

Attribute Name	Explanation
port	Sets the port number that the web server listens on. The installed value is a Java system property named: `application.portno` Note The startup script sets this system property. Unless you alter the start script, the default value in the MBean configuration file is ignored during application startup. To change the value of `application.portno`, edit the application-specific startup script. Default: 8080 Installed value: The SESM installation program sets the `application.portno` in the startup script to the application port that you provided during the installation process.
minThreads	Sets the minimum number of threads that this listener maintains during periods of low load. This listener always has system resources allocated for this number of threads. Installed default: 5
maxThreads	Sets the maximum number of threads that this listener can allocate resources for, even during peak loads. This listener can have up to this number of threads. Installed default: 255
maxIdleTimeMs	Specifies the length of time a thread can be idle (not used) before the listener deallocates it. The unit is milliseconds. Installed default: 60000
maxReadTimeMs	Specifies the time that a read on a request can block. This is the length of time that the web server waits for a request from a client after the client opens a socket connection. When maxReadTimeMs is exceeded, the web server closes the socket connection. Installed default: 60000

SESMSSLListener MBean

The SESMSSLListener MBean configures the port that the Jetty server listens on for requests from subscribers on the Secure Sockets Layer (SSL). Table 4-5 describes the attributes in the SESMSSLListener MBean.

Table 4-5: Jetty Container—SESMSSLListener MBean

Attribute Name Explanation

port

Sets the port that the secure socket layer (SSL) listener uses. The installed value is a Java system property named:

application.ssl.portno

Note The startup script sets this system property. Unless you alter the startup script, the default value in the MBean configuration file is ignored during application startup.

The generic startup script derives a value for application.ssl.portno based on the value of application.portno, as follows:

application.ssl.portno = application.portno - 80 + 443

To change the value of application.ssl.portno, edit the generic startup script.

MinThreads

Sets the minimum number of threads that this listener maintains during periods of low load. The listener always has system resources allocated for this number of threads.

Installed default: 5

MaxThreads

Sets the maximum number of threads that this listener can allocate resources for, even during peak loads. The listener can allocate up to this number of threads.

Installed default: 255

MaxIdleTimeMs

Specifies the length of time a thread can be idle (not used) before the listener deallocates it. The unit is milliseconds.

Installed default: 50000

Keystore

Sets the path name of the SSL keystore file. The keystore file is a binary file created by keytool. Sample keystore files are included in the installation for each portal application. For example:

: jetty.home/config/nwspkeystore

Where:

: jetty.home—A system property. The NWSP start script derives the value of jetty.home from an expected (installed) directory structure. To change the value of jetty.home, edit the start script. Unless you alter the start script, the default value for jetty.home specified in this MBean configuration file is ignored at run time.

Caution A keystore file is required for deployments that use HTTPS. HTTPS does not function without a valid keystore file. The nwspkeystore file included with the SESM installation works, but you should replace it with a keystore valid for your specific deployment. See the "Using HTTPS in SESM Portals" section for more information.

Password

Must match the value in the keystore file referenced above.

KeyPassword

Must match the value in the keystore file referenced above.

Table of Contents