J2EE Doc Bundle Home
Java

JavaTM 2 SDK, Enterprise Edition 1.3
Configuration Guide

 

Revised: 9/21/01

Contents

Introduction

This release, JavaTM 2 SDK, Enterprise Edition 1.3, stores configuration information in a set of properties files that reside in the config directory. You may edit these files with a text editor. This document describes the configuration parameters that you may edit in the properties files.

In most cases, you won't have to make any changes to the properties files. However, if you wish to use a database driver other than Cloudscape, you'll need to follow the instructions in the next section.

JDBCTM Drivers

This release includes a JDBC driver for the Cloudscape DBMS. This driver is already configured in the config/resource.properties file. No further changes by you are necessary. (If you encounter a port conflict with Cloudscape, please refer to the Port Numbers section.) By default, Cloudscape databases will be created in the cloudscape directory.

If your enterprise beans use the JDBC API to access a database other than Cloudscape, then you must configure the JDBC drivers according to the instructions in the sections that follow. (If you aren't sure if this release supports your JDBC driver, see the Supported Databases and JDBC Drivers section of the Release Notes.)

Note: After you configure a JDBC driver you must restart the J2EE server for the new configuration to take effect.

Driver Location

You must copy the JDBC driver JAR files to the $J2EE_HOME/lib/system directory. (Files in this directory have the java.security.AllPermission, needed because a driver may perform privileged operations.) Be sure to include the classpath to these JAR files in the J2EE_CLASSPATH environment variable.

J2EE_CLASSPATH

The J2EE server uses a JDBC driver to access a database. It locates the driver's JAR files by referencing the J2EE_CLASSPATH environment variable. You can set this environment variable on the command line before you run the J2EE server. However, we recommend that you set J2EE_CLASSPATH in the user configuration script. Editing the user configuration script is a required step during the installation procedure. On UNIX the user configuration script is in bin/userconfig.sh, and on Windows it is in bin\userconfig.bat.

About XA Datasource Support

Drivers that support XA datasources allow you to connect to multiple databases and to distribute transactions across machines or processes. JDBC 1.0 drivers do not support XA datasources. Some JDBC 2.0 drivers support XA datasources and some do not. If you do not know whether or not your driver supports XA datasources, please check with the driver's vendor.

If your driver does not support XA datasources, you must follow the instructions in the section, Drivers Without XA Datasource Support.

If your driver supports XA datasources, to take advantage of XA's features you must follow the instructions in the section, Drivers with XA Datasource Support.

If your driver supports XA datasources and you follow the instructions in the section, Drivers Without XA Datasource Support, the driver will work but cannot take advantage of XA's features.

Drivers Without XA Datasource Support

1. Add the JDBC driver.

Syntax:

j2eeadmin -addJdbcDriver <class name>
Example:

j2eeadmin -addJdbcDriver oracle.jdbc.driver.OracleDriver
2. Add the DataSource:.

Syntax:

j2eeadmin -addJdbcDatasource <jndi name> <url>
Example:

j2eeadmin -addJdbcDatasource \
jdbc/Oracle jdbc:oracle:thin@rtc:1521:acct
This command links the JNDI name of a DataSource with the URL of a database. Typically, the JNDI name is the logical name of a database. The URL specifies the actual location of a database. Neither the JNDI name nor the URL are hardcoded in the source code of an enterprise bean. To determine the format of the URL, please check the documentation provided by the vendor of the JDBC driver.

3. Update the J2EE_CLASSPATH. (See the J2EE_CLASSPATH section.)

4. Restart the J2EE server.

Drivers with XA Datasource Support

1. Add the DataSource.

Syntax:

j2eeadmin -addJdbcXADatasource <jndi name> 
<class name> 
[<xa user name> <xa password>] 
[-props (<name>=<value>)+]
Example:

j2eeadmin -addJdbcXADatasource jdbc/XAMerant
com.merant.sequelink.jdbcx.datasource.SequeLinkDataSource
buzz xhfu5k3t
-props serverName=myserver portNumber=19996
2. Update the J2EE_CLASSPATH. (See the J2EE_CLASSPATH section.)

3. Restart the J2EE server.

An Example resource.properties for Oracle

The default config/resource.properties file specifies a driver for the Cloudscape database. If you want to use an Oracle database, you may use a file similar to the following:

jdbcDataSource.0.name=jdbc/Oracle
jdbcDataSource.0.url=jdbc:sequelink://anybodys.eng.sun.com:19996
jdbcDriver.0.name=com.merant.sequelink.jdbc.SequeLinkDriver
jdbcXADataSource.0.name=jdbc/Merant
jdbcXADataSource.0.classname=com.merant.sequelink.jdbcx.datasource.
SequeLinkDataSource
jdbcXADataSource.0.dbpassword=
jdbcXADataSource.0.dbuser=
jdbcXADataSource.0.prop.serverName=anybodys
jdbcXADataSource.0.prop.portNumber=19996
jmsCnxFactory.0.name=QueueConnectionFactory
jmsCnxFactory.0.isQueue=true
jmsCnxFactory.1.name=TopicConnectionFactory
jmsCnxFactory.1.isQueue=false
jmsCnxFactory.2.name=jms/QueueConnectionFactory
jmsCnxFactory.2.isQueue=true
jmsCnxFactory.3.name=jms/TopicConnectionFactory
jmsCnxFactory.3.isQueue=false
jmsDestination.0.name=jms/Queue
jmsDestination.0.isQueue=true
jmsDestination.1.name=jms/Topic
jmsDestination.1.isQueue=false

Transactions

You can control transaction recoveries and timeouts by editing the config/default.properties file.

The distributed.transaction.recovery Property

This property controls whether or not distributed transactions will be recovered. For these transactions to be recovered, the following conditions must be met: The transaction encompasses multiple databases. The J2EE application accesses the databases with a JDBC driver that supports XA datasources. All of the parties involved in the 2-phase commit protocol have agreed to commit (or rollback) the transaction when the crash occurs. When the server starts up again, the transaction will be committed (or rolled back) during the recovery process.

The value of this property may be either true or false. When the J2EE SDK is first installed, the value is false:

distributed.transaction.recovery=false

The transaction.timeout Property

For enterprise beans with container-managed transactions, you control the transaction timeout interval by setting the value of the transaction.timeout property. For example, you would set the timeout value to 5 seconds as follows:

transaction.timeout=5
With this setting, if the transaction has not completed within 5 seconds, the J2EE transaction manager rolls it back.

When J2EE SDK is first installed, the timeout value is set to 0:

transaction.timeout=0
If the value is 0, the transaction will not time out.

Only enterprise beans with container-managed transactions are affected by the transaction.timeout property. For enterprise beans with bean-managed, JTA transactions, you invoke the setTransactionTimeout method of the UserTransaction interface. You also invoke the setTransactionTimeout method for other components, such as servlets and JSP pages, that demarcate transactions with the UserTransaction interface.

Port Numbers

The JavaTM 2 SDK, Enterprise Edition software requires several TCP/IP ports. To change a port number, edit the appropriate properties file in the config directory. The following table lists the ports and their corresponding properties files.

TABLE 1 JavaTM 2 SDK, Enterprise Edition Ports
Service
Using the Port

 Default
Port Number

 Properties File

 Default Entry
in Properties File

 Description

EJB 9191 ejb.properties http.port=9191 The EJB service uses this port to download stub classes to clients.
HTTP 8000 web.properties http.port=8000 The HTTP service uses this port to service requests.
HTTPS 7000 web.properties https.port=7000 The HTTPS service uses this port to service requests.
Naming and Directory 1050 orb.properties port=1050 The ORB (Object Request Broker) underlying the JNDI name server uses this port.

Cloudscape Port

By default, the Cloudscape database server uses port 1099. To change port 1099 to 1088, for example, you must make several changes:

1. Edit the bin/cloudscape script (bin\cloudscape.bat on Windows):

a. In the -start portion of the script, insert the port number:

. . . RmiJdbc.RJJdbcServer -port 1088. . .
b. In the -stop portion, insert the port number here:

jdbc:rmi://localhost:1088/jdbc:cloudscape:
c. In the -isql portion, change the 1099 port number to 1088.

2. In the config/resource.properties file, make this change:

jdbcDataSource.0.url=jdbc:cloudscape:rmi://localhost:1088/
CloudscapeDB;create=true
For the J2EE Tutorial, you'll also need to change port number 1099 in the build.xml files, which are located in your J2EE Tutorial installation:

  bank/build.xml
  examples/src/build.xml

Log Files

Each service -- J2EE, JMS, Web -- generates a group of log files. These files reside beneath the directory specified by this syntax:

$J2EE_HOME/<logs>/<host>
The <logs> element is the directory specified by the log.directory entry in the default.properties file. The default value is logs. The <host> element is the name of the computer.

J2EE Log Files

The J2EE log files reside in the following directory:

$J2EE_HOME/<logs>/<host>/j2ee/j2ee
The J2EE service generates these log files:

system.out
system.err
event.log
output.log
error.log
audit.log
The system.out and system.err files contain the output generated by enterprise beans that write to System.out and System.err. If you run j2ee with the verbose option, this output is written to stdout and stderr; the system.out and system.err log files are not created. The audit.log file is generated only if the audit property of the config/auth.properties file equals true.

Web Log Files

The Web log files reside in the following directory:

$J2EE_HOME/<logs>/<host>/web
The Web service generates catalina log files.

JMS Log Files

The JMS log files reside in the following directory:

$J2EE_HOME/<logs>/<host>/jms/jms
The JMS service generates these log files:

error.log
event.log
output.log

Changing Log File Names

The names of log files can be changed by editing the default.properties file. For example, you can change the name of the J2EE output.log file by modifying the value of the log.output property.

To modify the names of the log files created by the web service, edit these entries in the web.properties file:

access.log=access.log
error.log=error.log

Security

Unauthenticated User Name

Web applications accept unauthenticated web clients and allow them to make calls to the EJB container. The EJB specification requires a security credential for EJB method calls. Typically the credential will be that of a generic unauthenticated user. How this credential is provided is implementation dependent.

In the J2EE SDK the unauthenticated user is called a guest and has the password guest123. You can modify the name of the unauthenticated user and password by modifying the following entries in the auth.properties file: 

default.principal.name=guest
default.principal.password=guest123

ANYONE Role

In the Security tabbed pane of the deploytool, methods are assigned the ANYONE role by default. The ANYONE role represents the universal set of all users and groups. If you do not map a method to a role in the deploytool, any user or group may invoke the method. The default ANYONE role can be changed by editing the anyone.role.name entry in the auth.properties file.

Using Keystores with SSL Protocol

The SSL protocol is used for authentication and encryption of the communication channels between a clients, enterprise beans, or Web components. Keystore files containing the public, or private keys for a client or component are used for authentication with the SSL Protocol.

The J2EE SDK provides a default server keystore called the keystore.jks and a default client keystore called the clientkeystore.jks. These files are present in the J2EE SDK distribution's $J2EE_HOME/lib/security directory.

Another required keystore is the cacerts.jks file. This file must contain the public key certificates of the Certificate Authority or the client's public key certificate at the time the server is authenticating the client. The J2EE SDK provides a default cacerts.jks file, which resides in the $J2EE_HOME/lib/security directory.

Typically, a keystore file is protected by a password. The default value for this password is changeit for both the default keystore.jks and clientkeystore.jks files.

Authentication with SSL

Normal Authentication

In the normal SSL handshake with server-only authentication, a client asks the server to identify itself. The server responds by sending its public key certificate to the client and communication proceeds if the certificate is recognized by the client.

To enable SSL authentication for an enterprise bean, select the bean in the Tree view (the left panel) of the deploytool primary window and click on the Security tab. In the Security inspector in the right panel, click on Deployment Settings. Select the "SSL Required" check box in the Deployment Settings dialog. This will encrypt the session between the client and the bean with the server authenticating itself to the bean.

Run the application client using the runclient script.

Mutual Authentication

Mutual authentication requires that both the client and the server identify themselves, adding an additional degree of security. After the public key certificate from the server is received, the client sends its public key certificate to the server. The server looks at the Certificate Authority who signed the certificate and decides whether it can trust the certificate. This process is done transparently by the Java Secure Socket Extension (JSSE).

To start mutual SSL authentication, select the bean in the Tree view (the left panel) of the deploytool primary window and click on the Security tab. In the Security inspector in the right panel, click on Deployment Settings. Select the "SSL Required" check box in the Deployment Settings dialog as in normal SSL authentication. While in the Deployment Settings dialog, select the Certificate radio button in the Client Authentication pane. This will cause the application client to authenticate itself to the server.

For mutual SSL authentication, the path to the client's keystore file must be provided by setting the following system property in the VMARGS environment variable: 

-Dcom.sun.enterprise.keyStore=$J2EE_HOME/lib/security/
clientkeystore.jks
For application clients using mutual SSL with an enterprise bean, you will need to provide an additional property informing the application client container that SSL with client authentication will be used. The property is 

-Dcom.sun.enterprise.loginMech=ssl.
Finally, run the application client using the runclient script. This will pop up a dialog box asking for the keystore password. On successful entry of the keystore password (changeit for the default keystore). A list of certificates will be shown in a new dialog box. Select the valid certificate and press OK. This will start mutual authentication with SSL.

Troubleshooting Mutual Authentication

If the application client fails, check the following:

Checking that mutual authentication is running

You can check that mutual authenticating is running by doing the following:

1. In the setenv.sh file (Unix) or setenv.bat (Windows) find SSL_OPTIONS and turn on debug tracing properties in either of the following ways: 

-Djavax.net.debug=ssl,handshake
or 

-Djavax.net.debug=all
2. Restart the server in verbose mode.

3. Look for the following messages that verify that mutual authentication is running:

Procedures for Creating Custom Certificates

When the default keystores are inappropriate or missing, the keytool is used to replace them. (The keytool can be found in the bin directory of the J2EE SDK installation.)

Creation of a Server Certificate

We show here the creation of a server certificate:

1. Use the following instruction: 

keytool -genkey -keyalg RSA -alias server -keystore keystore.jks
You will be prompted for a password. Enter the default password changeit (The command to change the keystore password is keytool -storepasswd. Run keytool -help for the complete option list).

2. Enter your information for the following prompts:

    1. Name: J2EE
    2. Organization: Java Software
    3. Company Name: Sun Microsystems, Inc.
    4. Locality: Cupertino
    5. State: California
    6. Country: US
3. Export the server certificate to a certificate file for input to the realmtool:

keytool -keystore keystore.jks -export -alias server -file 
keystore.cer
4. Import the new server certificate into the Certificate Authority file cacerts.jks:

realmtool -import keystore.cer -alias server
Note: The default server certificate is already prepared. You do this only if you wish to replace the default server certificate.

Creating a Client Certificate

Creating a client certificate is similar to the procedure for server certificates set out above.

1. Use the keytool to create a server certificate in a keystore file of your choice: 

keytool -genkey -keyalg RSA -alias MyClientAlias -keystore 
mykeystore.jks
You will be prompted for a password. Enter changeit, as above. When requested enter the name, organization etc. for the client.

2. Export the new client certificate from the keystore to a certificate file: 

keytool -keystore mykeystore.jks -export -alias MyClientAlias -file 
myclientcert.cer
3. Import the new client certificate into the server's Certificate Authority file cacerts.jks. This allows the server to trust the client during SSL mutual authentication. 

keytool -import -alias j2eeCA -keystore $J2EE_HOME/lib/security/
cacerts.jks -file myclientcert.cer

Miscellaneous Commands for organizing certificates

1. To check the contents of the server certificate: 

keytool -list -keystore keystore -alias server -v
2. To check the contents of the cacerts file: 

keytool -list -keystore cacerts.jks

PKCS12 Support in the J2EE SDK

PKCS12 keys are supported in the J2EE SDK. PKCS12 allows a user to import, export and exercise a single set of personal identity information. A complete description is at 

http://www.rsasecurity.com/rsalabs/pkcs/pkcs-12/.

Generating a PKCS12 file

Netscape may be used to generate PKCS12 certificates:

1. Open Netscape

2. Click on the security icon

3. Under Certificates, Click on "Yours".

4. If there is a certificate, export it. Otherwise, click "Get a Certificate".

A certificate will be exported to PKCS12 format.

Using a PKCS12 key In J2EE

A PKCS12 format key must be converted into .jks format for use in the J2EE SDK. The keytool -pkcs12 command lists the options that allow you to import a PKCS12 file. The keystore password for the .jks file should be the one used for the J2EE keystore.

The command for the conversion is: 

keytool -pkcs12 -pkcsFile fileName -pkcsKeyStorePass password -
pkcsKeyPass password -jksFile outputFileName -jksKeyStorePass 
password
The result is a .jks file that has the key -- the private key and the certificate chain -- in the file.

To export the certificate into a certificate file for the realmtool, say abc.cer, use the keytool -export option: 

keytool -keystore keystore.jks -export -alias server -file 
keystore.cer
Use realmtool -import to import abc.cer into the certstore (See Creation of a Server Certificate above.)

If a certificate is from a Certificate Authority (CA) that is not the cacerts file of the J2EE SDK, use keytool -import on abc.cer to import it into the cacerts file. See the Creation of a Server Certificate section.

Memory Threshold for Passivation

When the EJB container passivates an enterprise bean, it saves the bean's state in secondary storage and attempts to reclaim memory. For stateful session beans, the Cloudscape database is used as secondary storage, so passivation will occur only if the Cloudscape database is started. By default passivation occurs only when memory usage in the server exceeds 128 megabytes. To change the default, you can modify the value of the passivation.threshold.memory property in the config/default.properties file: 

passivation.threshold.memory=128000000
This property indicates the memory usage threshold in bytes after which the container will start passivating beans. The value must be a positive integer. If you decrease the value of this property then passivation will occur more often.

HTTP Document Root

By default, the document root of the HTTP and HTTPS services is public_html. You may change the document root by editing the documentroot entry of the web.properties file. This entry is always relative to the J2EE_HOME environment variable. Here is the default entry in web.properties:

documentroot=public_html/

JMS Settings

The following tables list some of the JMS properties in the files of the config directory.

TABLE 2 JMS Settings in default.properties
Property Name

 Description

messagebean.pool.size Specifies the maximum number of instances of an mdb type. You cannot specify different pool sizes for different mdb types.
messagebean.max.serversessionmsgs Normally, when traffic is light, a ConnectionConsumer gets a ServerSession from its pool, loads it with a single message, and starts it. As traffic picks up, messages can back up. If this happens, a ConnectionConsumer can load each ServerSession with more than one message. This reduces the thread context switches, and minimizes resource use at the expense of some serialization of message processing. This release only supports the value 1.

TABLE 3 JMS Settings in jms_service.properties
Property Name

 Description

com.sun.jms.internal.java.naming.* Specifies the JNDI provider.
com.sun.jms.client.transport_preference Specifies the service used by the clients to communicate with the JMS service. The only supported value is IIOP. This value should not be modified.
com.sun.jms.service.bindAdministeredObjects Specifies whether or not the service should bind two default ConnectionFactory objects. This value should not be modified.
com.sun.jms.service.jdbc.* Specifies the JDBC provider. Currently set to Cloudscape, these values should not be modified.
com.sun.jms.default.loglevel Specifies the default log level. Valid settings are SEVERE, WARNING, INFO, FINE, FINER, FINEST
com.sun.jms.service.client_reaper_interval Specifies in minutes how often the JMS service should look for clients that have not closed their resources properly.

TABLE 4 JMS Settings in jms_client.properties
Property Name

 Description

com.sun.jms.internal.java.naming.* Specifies the JNDI provider.
com.sun.jms.client.transport_preference Specifies the service used by the clients to communicate with the JMS service. The only supported value is IIOP. This value should not be modified.
com.sun.jms.default.loglevel Specifies the default log level. Valid settings are SEVERE, WARNING, INFO, FINE, FINER, FINEST


Copyright © 2001 Sun Microsystems, Inc. All rights reserved.