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
Third Party JDBC Driver Support
Clusters and Data Synchronization
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)
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.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).
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:
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.
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.Update multiple databases that are distributed over different geographic locations.
Update multiple databases of different types (Oracle, Sybase, and so on).
You must provide the following transaction manager information for each KJS process:
A mirror directory for storing the restart.bak file.
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.
Driver
Platform
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:
Identifying the JDBC driver to iPlanet.
(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.Specifying the driver identifier and database connection information in datasource definitions used by your application.
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:
Driver
Class name
Driver CLASSPATH
The fully qualified path to the driver classes, JAR, or ZIP file. The following table gives typical Solaris and NT CLASSPATHS:
Driver
Typical Solaris CLASSPATH
Typical NT CLASSPATH
The path under which the native libraries supporting Type 2 drivers exist. The following Library Paths are for Type 2 JDBC drivers:
Driver
Solaris Library Path
NT Library Path
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\IS3PJDBCWhen 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:
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:
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:<jndi-name>jdbc/estore/EstoreDB</jndi-name>
<driver-type>ora-type4</driver-type>
<database-url>jdbc:oracle:thin:@hostname:1521:
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.
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
MaxPoolSize
- Set the KJS log file to display third party JDBC driver connection pooling diagnostic messages.
MaxWait
- Maximum number of physical connections to the database.
MonitorInterval Time
- Maximum wait time in seconds for a connection to be freed from the pool when all connections are already in use.
SteadyPoolSize
- Interval in seconds at which monitor thread will scan the pool to determine if unused physical database connections should be terminated.
UnusedMaxLife
- 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.
- 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:
Open String Information
The following table provides the open string formats for the different types of databases:
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.
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:
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