![]() |
JavaTM 2 SDK, Enterprise Edition 1.3.1 Configuration Guide |
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.
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.
$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
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 systems the user configuration script is in bin/userconfig.sh
, and on Windows it is in bin\userconfig.bat
.The instructions that you follow depend on whether or not your driver supports XA datasources:
Example:j2eeadmin -addJdbcDriver <class name>
2. Add thej2eeadmin -addJdbcDriver oracle.jdbc.driver.OracleDriver
DataSource
:.Example:j2eeadmin -addJdbcDatasource <jndi name> <url>
This command links the JNDI name of aj2eeadmin -addJdbcDatasource jdbc/Oracle jdbc:oracle:thin@rtc:1521:acct
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.)
DataSource
.Example:j2eeadmin -addJdbcXADatasource <jndi name> <class name> [<xa user name> <xa password>] [-props (<name>=<value>)+]
2. Update thej2eeadmin -addJdbcXADatasource jdbc/XAMerant com.merant.sequelink.jdbcx.datasource.SequeLinkDataSource buzz xhfu5k3t -props serverName=myserver portNumber=19996
J2EE_CLASSPATH
. (See the J2EE_CLASSPATH section.)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
config/default.properties
file.
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
transaction.timeout
property. For example, you would set the timeout value to 5 seconds as follows:With this setting, if the transaction has not completed within 5 seconds, the J2EE transaction manager rolls it back.transaction.timeout=5
When J2EE SDK is first installed, the timeout value is set to 0:
If the value is 0, the transaction will not time out.transaction.timeout=0
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.
config
directory. The following table lists the ports and their corresponding properties files.
1. Edit the bin/cloudscape
script (bin\cloudscape.bat
on Windows):
a. In the -start
portion of the script, insert the port number:
b. In the. . . RmiJdbc.RJJdbcServer -port 1088. . .
-stop
portion, insert the port number here:c. In thejdbc:rmi://localhost:1088/jdbc:cloudscape:
-isql
portion, change the 1099 port number to 1088.
2. In the config/resource.properties
file, make this change:
For the J2EE Tutorial, you'll also need to change port number 1099 in thejdbcDataSource.0.url=jdbc:cloudscape:rmi://localhost:1088/ CloudscapeDB;create=true
build.xml
files, which are located in your J2EE Tutorial installation:bank/build.xml examples/src/build.xml
The$J2EE_HOME/logs/<host>
<host>
element is the name of the computer.The J2EE service generates these log files:$J2EE_HOME/logs/<host>/j2ee/j2ee
Thesystem.out system.err event.log output.log error.log audit.log
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
.The Web service generates$J2EE_HOME/logs/<host>/web
catalina
log files.The JMS service generates these log files:$J2EE_HOME/logs/<host>/jms/jms
error.log event.log output.log
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 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 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.
The J2EE SDK provides a default server keystore called the keystore.jks
and a default client keystore called the clientkeystore.jks
. These files are 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 the default keystore.jks
, clientkeystore.jks
, and cacerts.jks
files.
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.
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:
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.keyStore=$J2EE_HOME/lib/security/ clientkeystore.jks
Finally, run the application client using the-Dcom.sun.enterprise.loginMech=ssl
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 click OK. This will start mutual authentication with SSL.
1. In the setenv.sh
(UNIX) or setenv.bat
(Windows) file, find SSL_OPTIONS
and turn on the debug tracing property in either of the following ways:
or-Djavax.net.debug=ssl,handshake
2. Restart the server in-Djavax.net.debug=all
verbose
mode. 3. Look for the following messages that verify that mutual authentication is running:
certificate client_to_server client_key_exchange client_to_server client_verify client_to_server
keytool
is used to replace them. (The keytool
can be found in the bin
directory of the J2EE SDK installation.)1. Use the following instruction:
You will be prompted for a password. Enter the default passwordkeytool -genkey -keyalg RSA -alias server -keystore keystore.jks
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:
realmtool
:4. Import the new server certificate into the Certificate Authority filekeytool -keystore keystore.jks -export -alias server -file keystore.cer
cacerts.jks
:5.Copy thekeytool -import -alias serverCA -keystore $J2EE_HOME/lib/security/ cacerts.jks -file keystore.cer
keystore.jks
file to the $J2EE_HOME/lib/security
directory.Note: The default server certificate is already prepared. You do this only if you wish to replace the default server certificate.
1. Use keytool
to create a server certificate in a keystore file of your choice:
You will be prompted for a password. Enterkeytool -genkey -keyalg RSA -alias MyClientAlias -keystore mykeystore.jks
changeit
, as above. When requested enter the name, organization, and other prompts for the client. 2. Export the new client certificate from the keystore to a certificate file:
3. Import the new client certificate into the server's Certificate Authority filekeytool -keystore mykeystore.jks -export -alias MyClientAlias -file myclientcert.cer
cacerts.jks
. This allows the server to trust the client during SSL mutual authentication. 4. Import a client certificate into the certificate realm:keytool -import -alias j2eeCA -keystore $J2EE_HOME/lib/security/ cacerts.jks -file myclientcert.cer
5. Copyrealmtool -import myclientcert.cer
mykeystore.jks
to $J2EE_HOME/lib/security/clientkeystore.jks
.To check the contents of the cacerts file:keytool -list -keystore keystore.jks -alias server -v
keytool -list -keystore cacerts.jks
http://www.rsasecurity.com/rsalabs/pkcs/pkcs-12/.
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.
.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:
The result is akeytool -pkcs12 -pkcsFile fileName -pkcsKeyStorePass password - pkcsKeyPass password -jksFile outputFileName -jksKeyStorePass password
.jks
file that has the key -- the private key and the certificate chain -- in the file. passivation.threshold.memory
property in the config/default.properties
file: 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.passivation.threshold.memory=128000000
config
directory.
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.