Previous     Contents     Index     DocHome     Next     
iPlanet Application Server Installation Guide



Appendix A       Configuring iPlanet Application Server


This explains how to configure iPlanet Application Server on Windows NT and Solaris. It includes the following topics:



Port Numbers

All ports you specify are listener ports. Valid port numbers must be within the acceptable range (1 to 65535 on NT, 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 NT. On Solaris, this port is used for the CGI to Executive Server (KXS) communication.

  • 10820 for the C++ Server (KCS) on NT. On Solaris, this port is used for the Java Server (KJS).

  • 10821 for the C++ Server (KCS) on Solaris.

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.



Web Server



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:

  • gxlib

  • APPS

  • registry

  • kdb

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 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. For information about the Executive Server, see the Overview Guide.



Database



When you create your own applications, you can elect not to specify the particular database you want the application to use. In this case, the application will attempt to connect to the configured databases in the priority order you specify during installation.



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.


Raw Partitions

Note the following 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.

The current capabilities and limitations of iPlanet Application Server thrid party JDBC support include:


Current Capabilities and Limitations


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 applications use JNDI and the datasource interface to interact with JDBC drivers, the DriverManager class is relayed 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. In the next release of iPlanet Application Server, third party JDBC configuration will be incorporated into the GUI administrative tools.

Table 4-1



Driver

Platform

Oracle 8i 8.1.6.0.1: Type 4 (thin)  

Solaris and NT  

Oracle 8i 8.1.6.0.1: Type 2  

Solaris and NT  

Merant (Intersolv) SequeLink Java 5.0  

Solaris and NT

(RDBMS platforms supported by SequeLink)  

Sybase jConnect for JDBC 5.2 Type 4

(with Oracle only)  

Solaris

NT  

DB2 6.1, server 5.2, DB2, 7.1 client, server 6.1  

NT only  

Access to MSFT SQL Server  

Available from Merant for NT only  


Configuration Overview

Using a third party JDBC driver in iPlanet for J2EE JNDI and datasource-based access, and iPlanet's connection pooling and local transaction management requires:

  1. Identifying the JDBC driver to iPlanet.

  2. 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.


Configuring 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 drives can be uses on NT and Solaris:

Table 4-2   

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  


Driver CLASSPATH
The fully qualified path to the driver classes, JAR, or ZIP file. The following table gives typical Solaris and NT CLASSPATHS:

Table 4-3

Driver

Typical Solaris CLASSPATH

Typical NT 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  

(not supported)  

D:\SQLLLIB\java\db2java.zip  

The path under which the native libraries supporting Type 2 drivers exist. The following Library Paths are for Type 2 JDBC drivers:

Table 4-4

Driver

Solaris Library Path

NT 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 driver have the same requirement).


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 NT 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 4-5

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:

  • Driver Type/Name

  • Connection URL

  • Authentication Data

  • Connection Pooling Settings

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 4-6   

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  


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 resreg 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


deploycmd and resreg Command Line Tools
The deploycmd tool is recommended for command line registration of datasources. Example:

deploycmd -f EstoreDB.xml -s admin:admin@localhost:10817

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. 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 4-7

    DebugLevel

    Effect

    0  

    No messages.  

    1  

    Common messages like pool status, connection being returned to the pool, etc.  

    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.



Resource Manager

Resource manager lets you connect to a database back end for global transactions. Configure one resource manager for each database back end that you want to connect to. If you decide that you want to configure iPlanet Application Server with resource manager, 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.

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.


Database Type Information

The following list contains the database types you can specify 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 4-8   

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=ksample1+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 manager
ID}"
 

TM=ENCINA, RmRecoveryGuid=
12345698247024507520450
2450420579
 



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.

For more information about distributed data synchronization, see the Administrator's Guide.

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.



Multiple Instances of iPlanet Application Server




Reasons for Installing 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).

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

The most straightforward method of implementing multiple clusters is to install every application server instance using a single Directory Server configuration. Each web server 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 through the entries in the 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 two solutions for this: keep state and session information in a shared (between clusters) resource, such as a database; 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.


Resource Issues


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.


Shared Java Environment

All instances should share a single instance of the JDK to reduce disk storage requirements.


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#60


Previous     Contents     Index     DocHome     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated February 09, 2001