Appendix A
Configuring iPlanet Application Server
This appendix explains how to configure iPlanetTM Application Server on Windows NT/2000 and SolarisTM platforms.
This appendix includes the following topics:
Configuring Port Numbers
All ports you specify are listener ports. Valid port numbers must be within the acceptable range (1 to 65535 on Windows, 1025 to 32768 on Solaris) and must be unique (not used by any other applications on your system).
The default port numbers are as follows:
10817 for the Administrative Server (KAS)
10818 for the Executive Server (KXS)
10819 for the Java Server (KJS) on Windows. On Solaris, this port is used for the CGI to Executive Server (KXS) communication.
10820 for the C++ Server (KCS) on Windows. On Solaris, this port is used for the JavaTM Server (KJS).
10821 for the C++ Server (KCS) on Solaris
9091 for IIOP by the CXS engine
9092 for the PointBase database
389 for the directory server
In most cases, use the default port numbers suggested by the installation program, unless you are configuring multiple Java and C++ Servers, which require a unique port number for each additional Java and C++ engine.
Setting the Common Environment Variables
On the Solaris platform, the common environment variable settings are recorded in a single script file, iasenv.ksh. The iasenv.ksh script records the common environment variable settings, such as CLASSPATH, GX_ROOTDIR and LD_LIBRARY_PATH.
Therefore, These settings are no longer set in each of the scripts located under the ias/bin or ias/jms/bin directory.
The script is located in the <iASInstallDir>/ias/env directory.
|
Note
|
If any of your current applications are reading environment information for kjs, kxs, etc, they need to be modified to read from iasenv.ksh.
If you face backward compatibility issues, you can define the required variables within iasenv.ksh instead of modifying the individual scripts, such as kxs and kjs.
-
If the same values are present in both iasenv.ksh script and other scripts which refer to iasenv.ksh (such as kjs), then depending on the location of the definition of that variable within these scripts, either iasenv.ksh script setting wouldbe considered (for example, when the variable is definedbefore the invocation of iasenv.ksh script within, say kjs) or the setting that is defined within the other script would be taken into account (for example, when the variable is defined after the invocation of iasenv.ksh script within kjs).
|
|
Caution
|
We recommend that you do not change the values in the iasenv.ksh script, unless absolutely necessary.
|
Configuring Web Servers
If you use one of the supported Web servers on the same machine as iPlanet Application Server, the connector plug-in configuration is automatic.
On Solaris, install iPlanet Application Server as the same user, or as a member of the same group that installed the web server iPlanet Application Server will interface with.
If you are installing iPlanet Application Server over an NFS-mounted file system, make sure you have the same read-write permission on the following directories as the user who installed the web server:
These are subdirectories in the iPlanet Application Server installation directory.
Manually Configuring a Web Server
When you install iPlanet Application Server, your web server is automatically configured for the Web Connector plug-in, meaning that all necessary directories and settings on the web server are updated.
If you have problems with the connection between iPlanet Application Server and your web server, you may need to manually reconfigure the web server after you've installed the Web Connector plug-in.
See the iPlanet Application Server Administrator's Guide for more information.
Webless Installations
In a webless installation, the web server and iPlanet Application Server reside on separate machines. You should consider security issues related to your firewall setup. If a firewall will exist between the iPlanet Application Server machine and the web server machine, consult with your security administrator before performing a webless installation. Make sure that the necessary ports on the firewall are open to allow the Executive Server (KXS) and the Web Connector plug-in to communicate.
Configuring Apache Web Server
Apache Web Server 1.3.19 is supported in the iPlanet Application Server 6.0 SP3 release. To use the Apache Web server with the iPlanet Application Server's Web Connector Plug-in, a few manual configuration steps have to be performed.
You must install and configure the Apache Web Server on the machine on which the Web Connector Plug-in is installed.
|
Note
|
To use the Apache Web Server, you must select either the iPlanet Web Server or Microsoft Internet Information Server (on Windows only) during the application server installation. After installing the iPlanet Application Server, install and configure the Apache Web Server.
|
To Install Apache Web Server on Solaris
Download the Apache web server 1.3.19 source files from the Apache Web site at www.apache.org and unpack the tar.gz file.
-
|
Note
|
ar should be in your PATH.
The owner/group of iPlanet Application Server and Apache should be the same. By default, Apache runs as nobody:nobody.
-
If you need to change the owner/group of iPlanet Application Server files say, to nobody:nobody, then type the following command:
-
chown -R nobody:nobody <iASInstallDirectory/ias/>
Apache recommends that the Web server not be run as root. For more information, see the Apache Web site.
To run as root, set the shell variable EXTRA_CFLAGS to -DBIG_SECURITY_HOLE, before compiling.
|
Go to the root directory where the source files are saved and run:
-
./configure --prefix=<Installation_Directory>
--enable-module=so --with-port=<PortNo.>
make
make install
-
|
Note
|
enable-module=so is mandatory
The port number value is optional, as it is set to 80, by default.
|
-
The Apache control script is called apachectl and is available in the bin directory of the installation.
-
To start the script, type:
-
apachectl start
-
To stop, type
-
apachectl stop
To Configure Apache Web Server on Solaris
Add the shell variables GX_ROOTDIR, LD_LIBRARY_PATH and LD_PRELOAD to the apachectl script:
Code Example A-1
|
# Additions for the iPlanet Application Server
|
#
|
GX_ROOTDIR=<iASInstallDir>/ias
|
export GX_ROOTDIR
|
LD_LIBRARY_PATH=${GX_ROOTDIR}/gxlib:$LD_LIBRARY_PATH
|
export LD_LIBRARY_PATH
|
LD_PRELOAD=${GX_ROOTDIR}/gxlib/libiasdl.so
|
export LD_PRELOAD
|
#
|
|
|
Note
|
Replace <iASInstallDir> with the installation directory of iPlanet Application Server.
Replace <ApacheInstallDir> with the installation directory of Apache web server.
The lines with LD_PRELOAD are required only for Solaris 2.6.
|
Add the following lines at the end of <ApacheInstallDir>/conf/httpd.conf
Code Example A-2
# Additions for the iPlanet Application Server
|
#
|
LoadModule nas_module<iASInstallDir>/ias/gxlib/libiASApachePlugin.so
|
AddModule iASApacheInterface.cpp
|
<Location "/">
|
SetHandler ias-handler
|
|
Copy the <iASInstallDir>/ias/GXApp and <iASInstallDir>/ias/ias-samples directories to the <apacheInstallDir>/htdocs/ directory.
-
The minimum, maximum and the starting number of Web servers can be controlled by the following keys in conf/httpd.conf. These are the default values provided by Apache:
-
MinSpareServers 5
-
MaxSpareServers 10
StartServers 5
All the web servers write to the same log file.
Modify the iPlanet Application Server registry using kregedit, as given in "Configuring iPlanet Application Server Registry".
To Install Apache on Windows NT/2000
Download and install the binaries for Apache 1.3.19 from the Apache Web site at www.apache.org. For more information on installing Apache on Windows NT, follow instructions on the Apache Web site.
To Configure Apache Web Server on Windows
Add the path of the Apache executable in the system variable PATH.
Add the path of iASApachePlugin.dll (the Web Connector Plug-in) to the system variable PATH.
-
The path will be <iASInstallDir>/ias/bin.
-
|
Note
|
Replace <iASInstallDir> with the installation directory of iPlanet Application Server.
|
Add the following lines at the end of <ApacheInstallDir>/conf/httpd.conf
Code Example A-3
#Additions for the iPlanet Application Server
|
#
|
LoadModule nas_module <iASInstallDir>/ias/bin/iASApachePlugin.dll
|
AddModule iASApacheInterface.cpp
|
<Location "/">
|
SetHandler ias-handler
|
</Location>
|
|
Copy the <iASInstallDir>/ias/GXApp and <iASInstallDir>/ias/ias-samples directories to the <ApacheInstallDir>/htdocs/ directory.
Modify the iPlanet Application Server registry using kregedit, as given in "Configuring iPlanet Application Server Registry"".
Configuring iPlanet Application Server Registry
After installation, use kregedit to modify the following keys in the iPlanet Application Server registry.
Set SOFTWARE/iPlanet/Application Server/6.0/CCS0/HTTPAPI/HTTPPort to the listening port of the Apache web server.
Set SOFTWARE/iPlanet/Application Server/6.0/CCS0/HTTPAPI/PATH and SOFTWARE/iPlanet/Application Server/6.0/deployment/LogicalName/WWW_DOCROOT to the document root directory.
Append the document root directory, <Apache_Installation_Directory>/htdocs, to SOFTWARE/iPlanet/Application Server/6.0/CCS0/TEMPLATE/PATH, separated by semi colons.
Installing the Web Connector Plug-in
The Web Connector plug-in passes requests from your Web server to the iPlanet Application Server. iPlanet provides Web Connector plug-ins for the following web servers:
If you install iPlanet Application Server on a different machine than where the Web Server resides, you are configuring what is referred to as a "webless installation" of iPlanet Application Server. If this is the case, you must install the iPlanet Application Server Web Connector plug-in on the web server machine.
Before you install the Web Connector plug-in, do the following:
Check whether or not the iPlanet Application Server 6.0 Web Connector plug-in has already been installed. If it's already installed, the Web Server instance is already configured for iPlanet Application Server and you do not need to re-install the plug-in.
-
If the plug-in is not installed, continue with Step 2.
Stop running your Web Server instance.
Log on as a user with administrative privileges before installing the iPlanet Application Server Web Connector plug-in.
On Solaris, log on as the root user or as a user from the same group as the root user, who installed iPlanet Application Server before installing the Web Connector plug-in.
-
This procedure assumes that you have already installed iPlanet Application Server and Directory Server.
To Install the Web Connector Plug-in on Solaris
After you finish installing iPlanet Application Server as a webless installation, take the installation CD-ROM to the machine (or machines) that hosts the Web Server and run the installation program.
Follow the instructions of the installation program.
For more information on the installation procedure, see Chapter 3 "Easy iPlanet Application Server Installations".
When prompted, select "iPlanet Servers" as the components to install.
Select Typical as the installation type.
Specify a target installation directory. Do not include spaces in the path name.
When prompted for the components you want to install, choose to install only the iPlanet Application Server.
When prompted to install the iPlanet Application Server components, select the iPlanet Application Server Web Connector Component.
Follow the instructions of the installation program.
More information about the iPlanet Application Server Web Connector Component is contained in the iPlanet Application Server Administrator's Guide, and in the Deployment Tool online help system.
To Install the Web Connector Plug-in on Windows
After you finish installing iPlanet Application Server in a webless installation, take the installation CD-ROM to the machine (or machines) that hosts the web server and run the installation program.
When prompted, select "iPlanet Servers" as the components to install.
-
For more information on the installation procedure, see Chapter 3 "Easy iPlanet Application Server Installations".
Select Typical as the installation type.
Specify a target installation directory. Do not include spaces in the path name.
When prompted for the components you want to install, select only "iPlanet Application Server 6.0" component.
Click the Change button.
-
The iPlanet Application Server subcomponent screen appears.
Select the "Web Connector Plug-in Component" and "Core Server Components" from the list of subcomponents.
Follow the instructions of the installation program.
Select OK on the final dialog to reboot your computer, so the new settings can take effect.
For more information about the iPlanet Application Server Web Connector Component, see the iPlanet Application Server Administrator's Guide, and in the Deployment Tool Online Help.
Registering the Plug-in on IIS 5.0 running on Windows 2000
On systems running Windows 2000 with IIS 5.0, the Web Connector Plug-in should be registered as an In-process IIS 5.0 service. By default, the Plug-in is registered as an Out-of-process IIS service.
Use the following steps to register the Web Connector Plug-in as an In-process service of IIS 5.0.
To register the Plug-in on IIS 5.0
Go to Start >Settings> Control Panel > Administrative Tools > Computer Management
-
The Computer Management window will open.
In the left pane, click on the + sign to expand Services and Applications > Internet Information Services > Default Web Site.
Right-click Cgi-bin and select Properties
Select the Virtual Directory tab
Under Applications Settings, click Create.
Select the pull-down menu next to Application Protection.
Select Low(IIS Process)
Click OK.
Running PointBase
An ORDBMS package - PointBase Network 3.5, is bundled with the iPlanet Application Server. PointBase enables you to test your applications without having to install, or have access to, a production level database.
PointBase is one of the options available during installation, under Application Server core components. You can choose to install or not install PointBase by selecting the PointBase DataBase Server option.
PointBase database server and its third party JDBC driver is automatically registered with the Administration Server. It also populates the sample databases of e-Store, J2EEGuide, Database, and Bank sample applications.
For more information on how to register database drivers and deploy applications, see the iPlanet Application Server Administrator's Guide.
To Start PointBase
On Solaris, go to the directory <iASInstallDir>/pointbase/network/bin and type:
pointbaseServer start
To stop, type:
pointbaseServer stop
This procedure works on Windows as well.
On Windows, click Start, then select Programs > PointBase Network 3.5 > PointBase Server to start the PointBase application.
To shutdown, use the Shutdown option from the PointBase administration console.
|
Note
|
The PointBase server is started automatically after installation of iPlanet Application Server is complete.
On Solaris, after installation is complete, the PointBase database package's administration console will be displayed. If you get an error message, and you are unable to view the dialog box, set the DISPLAY terminal variable to X.
|
By default, PointBase runs on port 9092. Therefore, make sure that no other service is running on port 9092 before installing iPlanet Application Server. Since each PointBase server uses port 9092 by default, only one PointBase instance can run on a machine at any given moment.
Also, ensure that other iPlanet Application Server services do not use the same port.
To Administer PointBase
Two administration utilities are available with PointBase Network 3.5—the GUI-based Pointbase Console and the command line utility PointBase Commander.
Both these tools are available in the following location:
On Windows
The administrative tools can also be accessed through the Start menu:
Go to Start, select Programs > PointBase Network 3.5 and then select PointBase Console or PointBase Commander.
On Solaris
To run startconsole, go to <iASInstalDir>/pointbase/client/examples/batch/unix/startconsole
To run startcommander, go to <iASInstallDir>/pointbase/client/examples/batch/unix/startcommander
|
Caution
|
We recommend that you do not use the PointBase Console and Commander available in <iASInstallDir>\pointbase\client, as they are not optimized for your iPlanet Application Server installation.
|
Configuring the Transaction Manager
Transaction manager in iPlanet Application Server provides support for the EJB transaction model for both bean and container-managed transactions. Transaction manager can be configured in two modes: global transaction mode, where transactions span multiple processes and data sources; and local transaction mode, where transactions cannot span databases and are local to a process.
Local transaction mode is recommended if your transactions do not span multiple databases. Local transactions offer better performance, and work across all iPlanet Application Server supported database backends.
Global transaction mode coordinates global transactions within a Java Server (KJS process). A global transaction can:
Update a database using one or more Enterprise Java Beans (EJBs) running concurrently for the same global transaction, from within one or more KJS processes. One EJB triggers another EJB to run, and they both participate in the same transaction.
Update multiple databases that are distributed over different geographic locations.
Update multiple databases of different types (Oracle, Sybase, and so on).
Transaction manager runs within a KJS process and creates two files: a restart file and a restart.bak file. You need to provide a log file for each KJS process.
You must provide the following transaction manager information for each KJS process:
A mirror directory for storing the restart.bak file.
-
The default directory is install directory/CCS0/TXNMGR_MIRROR/.
|
Note
|
-
This is the same path that is used to store the restart file. It is recommended that you store restart.bak in a different location than restart. Consider using a pointer to the different physical disk drive.
|
A log volume disk name for storing the log file.
-
The default name is install directory/CCS0/TXNMGR/ENGnumber/logVol, where logVol is the device name.
-
For each KJS process, ENGnumber changes to match the process number. So, for KJS1, the directory is install directory/CCS0/TXNMGR/ENG1; for KJS2, the directory is install directory/CCS0/TXNMGR/ENG2, and so on.
Guidelines Regarding Raw Partitions
Note the following guidelines when configuring your transaction manager:
Create a raw partition on a physical drive prior to running the installation program. At installation specify the path for this partition, including the raw device name. Refer to your operating system documentation for information on how to create a raw device.
If you intend to specify a file name, use the default drive and log volume disk name provided by the installation program.
If you specify the name of a log volume disk that is a raw partition, make sure to indicate during installation that it is a raw partition.
If you specify a raw partition, you must specify a starting page number (Offset value) during the installation. You must also specify the number of the pages (Size value) in the log file. Make sure that the size allocated for the log file is greater than 4 MB; the file should be greater than or equal to 1000 pages, at a size of roughly 4 KB per page.
If you prefer to store the log file somewhere other than a raw partition, create a directory and file on a different disk drive, specify this directory name during installation, and do not check raw partition. The file must be greater than 4 MB, so make sure you have sufficient disk space wherever you create the directory and file. Refer to your operating system documentation for information on how to create a directory and file on a different disk drive.
Third Party JDBC Driver Support
Prior to iPlanet Application Server 6.0 SP1, using third party JDBC drivers required you to manage the coupling of the JDBC drivers to your applications outside of the iPlanet Application Server management environment, and to forego the standard J2EE JNDI-based datasource access, connection pooling, and transaction management features built into the iPlanet Application Server driver. In SP1, support has been added for using JDBC drivers in conjunction with standard J2EE JNDI-based datasource access, and iPlanet Application Server connection pooling and transaction management features.
Support for the existing iPlanet Application Server Type 2 JDBC driver based on relational database management system (RDBMS) client libraries will continue until the next major iPlanet Application Server release. Third party JDBC support is envisioned to eventually replace the iPlanet Type 2 JDBC native client driver in iPlanet Application Server.
This section includes the following topics:
Current Capabilities and Limitations
The current capabilities and limitations of iPlanet Application Server third party JDBC support include the following issues:
These issues are described in the following sections.
Datasource-Based Connection Pooling
The new third party JDBC driver support manages connection pooling at the datasource level, while the existing iPlanet Type 2 JDBC driver manages connection pooling at the native driver level. Datasource level connection pooling enables you to more finely tune database access to application requirements.
No Application Impact
New and existing J2EE applications do not require modifications to switch between the iPlanet Type 2 JDBC driver and third party JDBC drivers. Only the underlying datasource registration needs to be changed when switching between driver types.
Path Settings Automatically Set in Runtime Environment
Upon registration, the CLASSPATHs of third party JDBC drivers and the native driver library path for Type 2 drivers are added to the application server's runtime environment. You do not need to modify the runtime environment separately.
Supports Concurrent Use of Both iPlanet Type 2 and Third Party JDBC Drivers
Under certain circumstances, you are able to use both third party drivers and the iPlanet Type 2 driver. Special considerations apply to global transactions. See the section describing Registry Settings for Third Party JDBC Drivers for specific capabilities and limitations.
Local Transaction Support
Currently, the iPlanet third party JDBC driver support does not support global transactions (sometimes referred to as distributed, heterogeneous transactions). For global transactions use the iPlanet Type 2 JDBC driver in conjunction with RDBMS native client drivers. As iPlanet implements a JTS-based transaction manager, support for third party JDBC drivers and global transactions will be provided.
Driver Must Support DriverManager Class
iPlanet's initial implementation of third party JDBC drivers includes only those drivers that support the DriverManager class. Although a pplications use JNDI and the datasource interface to interact with JDBC drivers, the DriverManager class is relied upon to load JDBC drivers.
Administration via Registry Editor and Command Line Tools
For now, third party JDBC driver setup and configuration is performed via the iPlanet Application Server Registry Editor and command line tools. You may define datasources in XML files, and either register them via a command line tool, or through the iPlanet Application Server Deployment Tool.
-
Table 6-1 Certified Drivers
|
Driver
|
Platform
|
|
Oracle 8i 8.1.7 Type 2 and Type 4 (thin)
|
Solaris and Windows
|
|
Merant (Intersolv) SequeLink DataDirect Java 5.1
|
Solaris and Windows
(all databases supported by DDJ5.1)
|
|
Sybase jConnect for JDBC 5.2 Type 4
|
Solaris and Windows
|
|
DB2 JDBC 7.1 client
|
Solaris and Windows
|
|
Access to Microsoft SQL Server
|
Available from Merant for Windows only
|
|
Informix JDBC v1.5
|
Solaris and Windows
|
Configuration Overview
Using a third party JDBC driver in iPlanet Application Server for J2EE JNDI and datasource-based access, and iPlanet Application Server's connection pooling and local transaction management requires:
Identifying the JDBC driver to iPlanet.
Specifying the driver identifier and database connection information in datasource definitions used by your application.
(If you desire to use a third party JDBC driver without iPlanet's JDBC integration, ensure that your application manually loads the driver (typically performed through the DriverManager class), and sets up the appropriate connection settings. Configure the application server runtime environment with the appropriate CLASSPATH and library path settings.
Preparing to Configure Third Party JDBC Drivers
The following information is required to identify a third party JDBC driver in iPlanet Application Server:
Driver Name
A logical name by which you identify the driver to iPlanet. This name is used to link datasource definitions back to a physical driver type. The name can be of any string value you choose. Examples include: "ora-type4", "ora-type2", and "jconnect".
Driver Class Name
The class name associated with the driver. See the JDBC driver supplier for this information. Following are examples of class names for third party JDBC drivers that can be used on Windows and Solaris:
Table 6-2 Class Names for 3rd Party JDBC Drivers
|
Driver
|
Class name
|
|
Oracle Types 2 & 4
|
oracle.jdbc.OracleDriver
|
|
SequeLink Java 5
|
com.merant.sequelink.jdbc.SequeLinkDriver
|
|
Sybase jConnect 5.2
|
com.sybase.jdbc2.jdbc.SybDriver
|
|
DB2
|
COM.ibm.db2.jdbc.app.DB2Driver
|
|
Informix
|
com.informix.jdbc.Ifx Driver
|
Driver CLASSPATH
The fully qualified path to the driver classes, JAR, or ZIP file. The following table gives typical Solaris and Windows CLASSPATHs:
Table 6-3 Typical Solaris and Windows CLASSPATHs
|
Driver
|
Typical Solaris CLASSPATH
|
Typical Windows CLASSPATH
|
|
Oracle Types 2 & 4
|
/oraclient/jdbc/lib/classes12.zip
|
D:\orant\jdbc\lib\classes12.zip
|
|
SequeLink Java 5
|
/sljc/driver/lib/sljc.jar
|
C:\sljc\driver\lib\sljc.jar
|
|
Sybase jConnect 5.2
|
/jConnect-5_2/classes/jconn2/jar
|
D:\jConnect-5_2\classes\jconn2.jar
|
|
DB2
|
/DB2DIR/java/db2java.zip
|
D:\SQLLLIB\java\db2java.zip
|
|
Informix
|
/lib/ifxjdbc.jar
|
D:\lib\ifxjdbc.jar
|
Third Party Native Driver Directory
The path under which the native libraries supporting Type 2 drivers exist. The following Library Paths are for Type 2 JDBC drivers:
Table 6-4 Library paths for Type 2 JDBC drivers
|
Driver
|
Solaris Library Path
|
Windows Library Path
|
|
Oracle Types 2
|
/oraclient//lib/
|
D:\orant\bin
|
Configuring Third Party JDBC Drivers
Third party JDBC drivers need be identified to iPlanet either during application server installation, or via registration tools after installation. Registration must occur on each application server instance housing applications with third party JDBC driver datasources. For example, if you are configuring a two node cluster of iPlanet Application Server, and you are making an application available on both nodes in the cluster, then you must register the third party JDBC driver with each instance. (Existing iPlanet Type 2 drivers have the same requirement).
This section describes the following topics:
During iPlanet Application Server Installation
You can configure the third party JDBC drivers only through the Custom installation option. If you use the Express or Typical installation, see the next section for configuring the third party JDBC drivers after installation of the application server.
During application server Custom installation, you can only choose to configure iPlanet Type 2, third party JDBC, or no JDBC drivers. Although you can only configure either the Type 2 driver or third party JDBC driver during installation, you can choose to configure both after installation.
After Installation
Configure third party JDBC drivers after installation by executing a JDBC driver configuration tool. When configuring after installation, you must restart the application server to apply the driver changes.
For Windows, execute the jdbcsetup.exe program. (Registration of iPlanet Type 2 JDBC drivers for the supported database platforms is automatic since iPlanet automatically recognizes the presence of the supported native client libraries).
For Solaris: execute the db_setup.sh script. (Same command used to configure iPlanet Type 2 drivers).
Registry Settings for Third Party JDBC Drivers
As you register third party JDBC drivers in iPlanet, you will see the following iPlanet Registry settings:
Driver Entry
SOFTWARE\iPlanet\Application Server\6.0\CCS0\DAE3\DRIVERS\<driver
name>\
Under this key, you will find the driver's class name.
When you register a third party JDBC driver, a flag is set in the existing iPlanet Type 2 JDBC driver area of the Registry:
Third Party JDBC Flag
SOFTWARE\iPlanet\Application Server\6.0\CCS0\DAE2\IS3PJDBC
When set to on ("1"), the RowSet and transactional capabilities orient towards third party driver support. When using only third party JDBC drivers in your application, this flag should always be set to on.
This flag is set by the installation program and command line third party JDBC driver registration tools. Configuring an iPlanet Type 2 driver turns it off. If needed, you can manually change this flag via the iPlanet Application Server Registry Editor (kregedit). The following table provides scenarios and associated IS3JPDBC flag settings:
Table 6-5 IS3JPDBC flag settings
|
Scenario
|
Capabilities /Limitations
|
IS3PDBC Setting
|
Server Transaction Mode
|
|
Using third party JDBC drivers only
|
Local transactions are supported in both a programmatic mode throughout the web and EJB containers as well as in a declarative mode for EJBs.
|
On ("1")
|
Local only
|
|
Using iPlanet Type2 drivers only
|
Local and global transactions are supported in both programmatic and declarative styles.
|
Off ("0")
|
Local or global
|
|
Mix of third party and iPlanet Type 2 drivers
|
Local transactions are supported in web container via third party drivers. Global and local transactions supported in both web and EJB containers via iPlanet Type 2 driver.
|
Off ("0")
|
Local or global
|
Configuring JDBC Datasources for Your Applications
Once you have registered a third party JDBC driver with the application server, you must define JDBC datasources for applications to be able to interact with your database management system. A datasource in iPlanet Application Server holds the following information:
Except for connection pooling settings, this information is specified when registering a datasource with command line tools.
Datasource Information Requirements
This section describes the information required to register a JDBC datasource associated with a third party JDBC driver in iPlanet Application Server. Once you've registered a JDBC datasource in iPlanet, you can modify the connection pooling settings via the iPlanet Application Server Registry Editor.
Required Data
The JNDI-name uniquely identifies the datasource within the JNDI namespace of the application server. For example, a JNDI name of dbc/estore/EstoreDB would be referenced in ias-web.xml and ias-ejb-jar.xml files <resource-ref> entries of J2EE applications. The <resource-ref> entries map resource names used by J2EE applications to JNDI names defined within the application server.
The driver-type maps to the logical name assigned to third party JDBC driver.
The database-url is the database connection. See JDBC driver vendor documentation for driver-specific formats.
Following are examples of URL formats:
Table 6-6 Database URL formats
|
Driver
|
Class name
|
|
Oracle Types 2 & 4
|
jdbc:oracle:oci8:@MyHostString jdbc:oracle:thin:@myhost:1521:orcl
jdbc:oracle:thin:scott/tiger@myhost:1521:orcl jdbc:oracle:oci8:scott/tiger@myhost
|
|
SequeLink Java 5
|
dbc:sequelink://sequelinkhost:19996
jdbc:sequelink://192.168.5.96:19996;user=john;password=whatever
jdbc:sequelink://192.168.5.96:19996;databaseName=stores7
jdbc:sequelink://192.168.5.96:19996;databaseName=pubs;HUser=john;HPassword=whatever
jdbc:sequelink://sequelinkhost:4006;databaseName=pubs;DBUser=john;DBPassword=whatever
jdbc:sequelink:ssl://mysecurehost:9500;cipherSuites=SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
jdbc:sequelink:ssl://mysecurehost:9502;
|
|
Sybase jConnect 5.2
|
jdbc:sybase:Tds:host:port
|
|
DB2
|
db2:jdbc:dbname
|
|
Informix
|
jdbc:informix-sqli://mysecurehost:1528/database:informixserver=my_server
|
|
PointBase 3.5
|
jdbc:pointbase://localhost/j2eeguide, max.connections=100
|
Optional Data
The following optional data is conveyed to the third party driver on the DriverManager.getConnection(URL, properties) as name value pairs in the properties parameter. The usage of each property is driver-dependent.
The username is supplied to the RDBMS when iPlanet makes a connection to the database. Username and password are optional, since they can be supplied either programmatically, or on the connection URL.
The password is supplied to the RDBMS when iPlanet makes a connection to the database.
(The iPlanet Type 2 driver also supports the datasource and database fields in the datasource registration. Since the information represented by these fields is typically defined in the database connection URL, these fields are not supported in datasource definitions for third party JDBC drivers.)
Datasource XML File Example
The following example illustrates an XML file associated with a datasource based on a connection to an Oracle Type 4 driver:
<ias-resource>
<resource>
<jndi-name>jdbc/estore/EstoreDB</jndi-name>
<jdbc>
<driver-type>ora-type4</driver-type>
<database-url>jdbc:oracle:thin:@hostname:1521:
orcl</database-url>
<username>estore</username>
<password>estore</password>
</jdbc>
</resource>
</ias-resource>
You could either use the iasdeploy or regdatasource command line tool or the Deployment Tool to register this datasource. For more examples, see the Bank and Java Pet Store (estore) sample applications at <iAS install path>/ias/ias-samples/.
To use a different third party JDBC driver for this datasource, modify the <driver-type> and the <database-url>. This driver must already be registered in iPlanet. Restart the application server after reregistering the datasource.
Datasource Registration Tools
iasdeploy and regdatasource Command Line Tools
The iasdeploy tool is recommended for command line registration of datasources. Example:
-
iasdeploy regdatasource EstoreDB.xml
If you are registering against a local server, you can use the resreg command:
-
resreg EstoreDB.xml
Deployment Tool
Start the Deployment Tool (deploytool) and go to Tools->Register Datasource. Open an existing XML file of the form described above, or create a new datasource by filling the required and optional fields. Select Register to register the datasource with one or more application server instances.
Datasource Registry Settings
As you register datasources associated with third party JDBC drivers in iPlanet, you will see the following iPlanet Registry settings:
Datasource Entry
SOFTWARE\iPlanet\Application Server\6.0\DataSource\<jndi-name>\
The jndi-name is specified during registration of the datasource.
Connection Pooling Parameters
Connection pooling parameters are not currently defined during datasource registration. You can specify these parameters using the Administration Tool and selecting Database > External JDBC DataSource.
A set of default values are applied to each datasource as the datasource is registered. You can modify the connection pooling parameters via the iPlanet Registry Editor (kregedit).
SOFTWARE\iPlanet\Application Server\6.0\CCS0\POOLS\<portion of
jndi-name>\
The <portion of jndi-name> is the JNDI name specified in the datasource XML except for the jdbc\ portion. For example, estore/EstoreDB/.
DebugLevel
-
Set the KJS log file to display third party JDBC driver connection pooling diagnostic messages.
-
Table 6-7 KJS log file settings to display diagnostic messages
|
DebugLevel
|
Effect
|
|
0
|
No messages.
|
|
1
|
Common messages like pool status, connection being returned to the pool, and so on.
|
|
2
|
Output from option 1 and messages to indicate whether a connection is coming out of pool or causing a new connection. This is also used when you want to monitor how your pools are getting shrunk.
|
MaxPoolSize
-
Maximum number of physical connections to the database.
MaxWait
-
Maximum wait time in seconds for a connection to be freed from the pool when all connections are already in use.
MonitorInterval Time
-
Interval in seconds at which monitor thread will scan the pool to determine if unused physical database connections should be terminated.
SteadyPoolSize
-
Minimum size of pool. Once number of physical database connections reach the SteadyPoolSize, this number of connections will be maintained regardless of UnusedMaxLife setting. If SteadyPoolSize and MaxPoolSize are set to the same value, UnusedMaxLife does not apply. The monitor thread still executes, but returns as soon as it determines that steady and max values are identical.
-
In iPlanet Application Server, physical database connections are established an as needed. Even though SteadyPoolSize is set to a certain value, the application server will not create physical database connections until application requests access the connection pool. Physical connections are accumulated based on the settings of Steady and MaxPoolSize, as well as UnusedMaxLife.
UnusedMaxLife
-
If physical database connections exceed the number specified in SteadyPoolSize, UnusedMaxLife specifies the idle time in seconds after which a physical connection is eligible for deletion during the next execution of the monitor interval.
Configuring the Resource Manager
Connections to the database back-end for global transactions is mediated through the resource manager provided by the database vendor. Before using these databases in a global transaction, you should configure iPlanet Application Server connectivity to their resource managers. This configuration must be done before starting iPlanet Application Server.
If you enable a resource manager, whenever you start a KJS process, the transaction manager attempts a connection using the resource manager information you provided.
|
Note
|
We recommend that you do not have multiple resource manager connectivity configured for the same database.
|
You must define the following information for each resource manager: the database type, whether or not the resource manager is enabled, and an open string.
Database Type Information
You can specify the following database types for a resource manager:
Oracle
Sybase
IBM DB2
Microsoft SQL
Open String Information
The following table provides the open string formats for the different types of databases:
Table 6-8 Open string formats
|
Database
|
Format
|
Example
|
|
Oracle
|
Oracle_XA +
Acc=P/user/password (or Acc=P//) +
SesTm=session_time_limit +
(optional_fields)
DB=db_name +
GPwd=P/group_password +
LogDir=log_dir +
|
Oracle_XA+SqlNet=
ksample1+DB=Any_Logical_Name+Ac
c=P/kdemo/kdemo+SesTm=
90+LogDir=/export/TxnLog/
tmp+Threads=True
|
|
Sybase
|
U username -P password -N lrm_name
[ -V version] [ -C connections] -L logfile
[ -T trace_flag]
|
-Usa -P -Nksample_rm -Txa
-L/tmp/syb_xa_log
|
|
DB2
|
database name, user name, password
|
ksample, inst1, inst1
|
|
Microsoft SQL
|
TM=ENCINA, RmRecoveryGuid= resource manager ID
Note: The resource manager ID is available in the following location of the Microsoft SQL Server registry:
[HKEY_LOCAL_MACHINE\SOFTWARE
\Microsoft\MSSQLServer\MSSQLServer]
"ResourceMgrID"="{resource managerID}"
|
TM=ENCINA, RmRecoveryGuid=
12345698247024507520450
2450420579
|
For more information on open string formats, see the respective database vendor's website.
Configuring Clusters and Data Synchronization
Distributed data synchronization maintains the integrity of shared information across multiple iPlanet Application Server machines. This is crucial for partitioned and distributed applications that are hosted on multiple iPlanet Application Server machines.
A cluster is more than one instance of iPlanet Application Server, each installed on a separate machine, that can participate as a group in synchronization of state and session data. Each server within a cluster can assume one of several roles. Most important for this installation discussion is the category of Sync Server, which includes the Sync Primary, Sync Backup, and Sync Alternate servers.
The Sync Primary is the primary data store, to which all other servers in a cluster communicate for the latest distributed data information.
A Sync Backup mirrors the information on the Sync Primary, and takes over the role of the Sync Primary if the original Sync Primary fails.
A Sync Alternate is eligible to become a Sync Backup. If the number of Sync Backups falls below the set maximum, the Sync Alternate with the highest priority relative to other Sync Alternates is promoted to Sync Backup.
|
Note
|
If your configuration consists of only one instance of iPlanet Application Server, then cluster planning is not necessary.
|
When configuring your cluster, consider how many servers have the potential to become the Sync Primary. The maximum is the number of iPlanet Application Server machines in your network.
The Sync Primary is determined by which machine you start up first, after all servers are installed, and not by which machine has the highest priority assignment.
Note the priority rating you assign to the iPlanet Application Server machines in the cluster. For each installation of iPlanet Application Server in the cluster; you must re-enter the IP address, KXS port number, and priority number for every server in the cluster.
You should assign the highest priority to the iPlanet Application Server instance you prefer to be the Sync Primary, and start that machine up first. Assign the next highest priority to the Sync Backup; and assign those remaining to Sync Alternates, in the desired order of promotion.
You do not have to install the servers in the same priority order, as long as the priority rating and application server identification information is consistent across each installation.
For more information on configuring distributed data synchronization, see the iPlanet Application Server Administrator's Guide.
Reasons for Installing Multiple Instances
Installing multiple instances of iPlanet Application Server provides numerous advantages in both development and production environments. The following topics elaborate on the associated benefits and issues when running multiple instances.
Isolating Code
For Developers to ensure that a development team can work efficiently on shared systems, it is important to run code in separate processes, as in a Java Virtual Machine (JVM) for Java code, so that bugs in one developer's code will not bring down the development environment for the entire team. The current implementation of the iPlanet Application Server can isolate application components to individual instances of the application server, but cannot resolve to JVMs within an instance. Consequently, developers who share computer resources need to have multiple instances of the application server installed on their shared system(s). For developer installations, multi-instance installations should include separate web, application server, and directory instances.
In a production environment, it is usually necessary to update releases of the application without taking down the server. To accomplish this, iPlanet Application Server requires multiple JVMs and a stop/start for each JVM process. To reduce the impact of an update for one application on the rest of the applications, multiple instances of the application server can provide multiple platforms on which to deploy the unrelated application components. In that way, a single instance can be stopped/started to update any given application.
Improving Scalability
Each instance of the iPlanet Application Server scales well up to twelve processors. However, contention for resources causes performance to increase by lesser and lesser amounts as processors are added. By installing multiple instances, and binding processes to processors, a single large system looks like a number of smaller virtual systems. Dividing up the resources in this manner lessens resource contention and enables higher overall system performance.
Failover Issues
iPlanet Application Server clusters provide high availability (HA) by storing state and session information on one of the servers in the cluster, called the Sync Primary, and copying to another server in the cluster, called the Sync Backup. The Sync Primary and Sync Backup are determined by the boot sequence of the application server instances. The first instance in the cluster to come up becomes the Sync Primary, and the second instance becomes the Sync Backup.
If any of the instances of a cluster are on the same system, the odds are extremely high that both the Sync Primary and Sync Backup will be located on the same computer system. Failure of a single computer could bring down the entire cluster. To avoid this, each instance on the server should be clustered with at least one other instance on a separate server. This implies that a production site will be composed of multiple clusters. The number of clusters is minimally the largest number of instances that are created on a single server. For optimal performance, clusters should be composed of pairs of instances.
Multi-cluster Issues
To ensure that requests are routed correctly after a web server failure, the topology of a multi-cluster installation should allocate specific web servers to each cluster. Consequently, the configuration information for the clusters should either be in separate subtrees of one iPlanet Directory Server or in separate iPlanet Directory Servers.
Each webserver uses a plug-in to route requests to the iPlanet Application Servers. This plug-in, referred to as the web connector, identifies the available application servers in the cluster through the entries in the cluster's shared directory server.
A session beginning in one cluster, and subsequently load balanced to a different cluster, which does not have access to the state/session information generated by preceding requests creates a problem. To prevent this situation, the load balancer for the web servers must be sufficiently sophisticated to apply sticky load balancing for all requests associated with a particular session.
Load balancing solutions generally use two methods to accomplish sticky load balancing for sessions: base the stickiness on a cookie with the session ID, or base the stickiness on the source IP address of the request. For SSL encrypted sessions, the contents of the cookie are not available to the load balancer, so the source IP address is used. Unfortunately, some ISPs use proxies for their customers' web browsing sessions. Since the session can be load balanced between these proxies, the source IP address for the request can change, even though the request belongs to the same session.
Currently, there are three solutions for this situation:
Use an SSL appliance between the Internet and the web tier's load balancer so that the cookies are already decoded, or
Use a load balancing solution that allows the Network Administrator to enter known ISP proxy addresses to be consistently routed to a particular cluster, or
Keep state and session information in a shared (between clusters) resource, such as a database.
Resource Issues
This section discusses resource sharing and configuration options in an iPlanet Application Server cluster that can impact resource utilization. The following topics are covered:
Unique Network Ports
During installation, the iPlanet Application Server must be configured to communicate on particular network ports for its individual services. Use the Custom Installation to configure these ports to non-default values. For the installation of multiple instances on a single server, it is necessary to select different network ports for each instance, to avoid contention for resources.
For example, you typically install the Administrator process to port 10817, the Executive process to port 10818, and the first Java service to port 10820. If the first instance is installed with those defaults, you might install second instance with the Administrator process at port 11817, Executive at port 11818, and first Java service at port 11820.
Shared Directory Configuration Trees
For ease of administration and optimal load balancing across all of the iPlanet Application Server instances, the simplest configuration shares a common directory server with a common configuration tree (default is iasconfig). Due to the potential failure scenario described above in Multi-cluster Issues, you should separate all instances associated with the cluster allocated to serving a given ISPs proxies into a separate configuration tree. A subset of the web server instances will be allocated to that cluster as well.
Login
For each instance on a server, you should create a separate login. During installation, the iPlanet Application Server processes should be owned by the associated login. Separating ownership of the different instances eliminates ambiguity for the startup and shutdown scripts.
Anticipated Performance Benefits
Estimating performance for the many possible configurations is a complicated process. Use the Performance Tool for estimates. An example of the potential performance boost might be to compare the performance of a cluster of (2) 12-way E4500 servers to a multi-instance deployment using the same hardware: (12) clusters of (2) instances each. The multi-instance deployment should perform about twice as fast as the initial configuration.
Troubleshooting
After you install iPlanet Application Server, consider the following issues.
After installing iPlanet Application Server, make sure that the iPlanet Application Server gxlib directory (install directory/ias/gxlib) and the registry directory (install directory/ias/registry) are accessible by the web server owner and user.
Ensure that "CGI file type" is enabled on your web server. For iPlanet Web Server, go to the Server Administrator page, and under the Programs folder, click Yes for CGI file type.
When running applications, if the iPlanet Application Server Class Loader is unable to find the AppLogic class file through the SYSTEM_JAVA parameter (the registry parameter that contains both the CLASSPATH and GX_CLASSPATH settings), the request is handed over to the JAVA Class Loader, which in turn reads the CLASSPATH environment variable to find the class file. This allows AppLogics and servlets to execute even if the user CLASSPATH is not specified.
Check for required operating system patches. See the Release Notes to determine what patches you may need.
Check the latest Release Notes for workarounds to any problems you might encounter with installation at:
http://docs.iplanet.com/docs/manuals/ias.html