Chapter 2   Configuring iPlanet Application Server


This chapter explains how to configure iPlanet Application Server (iAS) on Windows NT and Unix. It includes the following topics:

• Server Components

• Directory Server

• Administration Server

• Port Numbers

• Web Server

• Database

• Transaction Manager

• Resource Manager

• Clusters and Data Synchronization

• Post-Installation and Troubleshooting Notes

Refer to this chapter while installing iAS for information about configuring application server components.

Server Components

---

The following describes the components you can install with iAS:

• iPlanet Application Server includes iAS, iAS Administrator, the Web Connector plug-in used to communicate between iAS and the web server, and the Deployment Manager.

• Netscape Console provides the common user interfaces for all iPlanet server products. From it you can perform common server administration functions such as stopping and starting servers, installing new server instances, and managing user and group information. Netscape Console can be installed stand-alone on any machine on your network and used to manage remote servers.

• iPlanet Administration Server is a common front end to all iPlanet servers. It receives communications from Netscape Console and passes those communications on the appropriate iPlanet server. Your site will have at least one Administration Server for each server root in which you have installed a iPlanet server.

• iPlanet Directory Server is iPlanet's LDAP implementation. The Directory Server runs as the slapd service on your NT machine (ns-slapd process on Unix operating systems). This is the server that manages the directory databases and responds to client requests.

Directory Server

---

Read the iPlanet Directory Server documentation, particularly the iPlanet Directory Server 4.0 Installation Guide, for information about setting up Directory Server and details about the issues discussed in this section. All Directory Server documentation is located in the following places:

• At http://docs.iplanet.com/docs/manuals/directory.html

• From the Help menu in Directory Server.

You can choose to install Directory Server with iAS or connect iAS to an existing Directory Server.

If you install Directory Server with iAS, you must designate this installation of Directory Server as the configuration directory, even if another installation of Directory Server already exists at your site.

The configuration directory contains the o=NetscapeRoot tree used by your iPlanet servers. The o=NetscapeRoot tree is where all the configuration settings of your iPlanet servers are stored.

If you do not install Directory Server with iAS, you must designate an existing Directory Server as the configuration directory. Make sure that the Directory Server you designate as the configuration directory contains the o=NetscapeRoot tree.

`The iAS installation program will prompt you for the following information about the existing Directory Server:

• The host name and port number for the machine where the existing Directory Server is installed.

• Login ID and password to connect to the existing Directory Server installation.

• Administrator login ID and password

Multiple iAS installations can store their configuration settings on the configuration Directory Server. To avoid your settings being overwritten by another iAS installation's configuration settings, assign a unique global configuration name to your iAS installation's settings. This name appears in the o=NetscapeRoot tree along with the global configuration names of other iAS installations.

During installation, you are asked to provide the global configuration name for the configuration settings of the iAS you are currently installing. Note that if you want to share configuration settings with other iAS installations, simply enter the same global configuration name for each installation.

The configuration directory contains an administration domain, which allows you to group iPlanet servers together so that you can more easily distribute server administrative tasks across organizations while retaining centralized control. Decide if you want to use administration domains, and if so, select the name(s) you want to use. It is recommended that you use names that correspond to the organizations that will control the servers in each domain.

Directory Manager DN

---

The installation program asks you to specify a Directory Manager distinguished name (DN) and password. Directory Manager DN is the special directory entry to which access control does not apply. Think of directory manager as your directory's superuser.

The default Directory Manager DN is cn=Directory Manager. Because the Directory Manger DN is a special entry that is not stored in the directory tree (instead it is stored in slapd.conf), it does not have to conform to any suffix configured for your Directory Server. Also, you should not create an actual Directory Server entry to use with the Directory Manager DN.

The Directory Manager password must be at least 8 characters long.

Administration Server

---

The iPlanet Administration Server is a common front end to all iPlanet servers. It receives communications from Netscape Console and passes those communications on to the appropriate iPlanet server. Your site will have at least one Administration Server for each server root in which you have installed a iPlanet server. During installation you are prompted for an Administration Server port number. This is the port number that your system administrator must specify to access the Administration Server.

Make sure the port number you select for the Administration Server is unique and has not been assigned earlier during the installation process to the non-SSL port number for the configuration server.

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, the default port numbers suggested by the installation program are adequate, unless you are configuring multiple Java and C++ Servers, in which case you assign a unique number to each additional Java and C++ engine.

Web Server

---

If you use one of the supported web servers on the same machine as iAS, the connector plug-in configuration is automatic.

On Solaris, install iAS as the same user or as a member of the same group that installed the web server with which iAS will interface.

Note: If you are installing iAS 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 iAS installation directory.

Manually Configuring a Web Server

---

When you install iAS, your web server is automatically configured for the Web Connector plug-in, meaning that all the necessary directories and settings on the web server are updated. However, there may be occasions, when, after you've installed the Web Connector plug-in, you must manually reconfigure the web server. This procedure is recommended only if you are having problems with the connection between iAS and your web server.

See the Administration and Deployment Guide for more information.

Webless Installations

---

In a webless installation, the web server and iAS reside on separate machines.

In a non-webless installation, iAS and the web server reside on the same machine.

Consider security issues related to your firewall setup. In a webless install of iAS, if a firewall will exist between the iAS machine and the web server machine, before installing iAS, consult with your security administrator to ensure that the necessary ports on the firewall are open so that the Executive Server (KXS) and the Web Connector plug-in can communicate. For information about the Executive Server, see the Overview Guide.

See the previous chapter, Installing iPlanet Application Server, for more information about installing the web connector plug-in.

Database

---

In addition, 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 attempts connecting to the configured databases in the priority order you specify during installation.

Transaction Manager

---

Transaction manager in iAS 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 are 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 iAS-supported database backends.

Transaction manager is a feature that coordinates global transactions within a Java Server (KJS process). A global transaction can:

• Update a database using one or more Enterprise Java Beans (EJB) running concurrently for the same global transaction, from within one or more KJS processes. This occurs when an 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. In addition, you need to provide a log file for each KJS process.

You must provide the following transaction manager information:

• A mirror directory for storing the restart.bak file of each KJS process.

  The default directory is install directory/CCS0/TXNMGR_MIRROR/.

  Note that 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.

• For each KJS process, 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 and then, 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; in other words, the file should be greater than or equal to 1000 pages, at a size of roughly 4 KB per page.

• If you do not create a raw partition on a disk drive, and do not want to use the default drive and file name because you'd rather store the log file elsewhere, create a directory and file on a different disk drive, specify this directory name at installation time, and make sure you do not specify that it is a raw partition. Note that 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.

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 iAS 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, when the KJS process starts up the transaction manager within that KJS process attempts a connection using the resource manager information you provide.

Database Type Information

The following list contains the database types you can specify for a resource manager:

• Oracle

• Sybase

• DB2

• Microsoft SQL

Open String Information

The following table provides the open string formats for the different types of database back ends:

Table 0.6

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 iAS machines. This is crucial for partitioned and distributed applications that are hosted on multiple iAS machines.

For more information about distributed data synchronization, see the Administration and Deployment Guide.

A cluster is more than one instance of iAS, 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 iAS, then cluster planning is not necessary.

When configuring your cluster, consider how many Sync Servers are in the cluster. In other words how many servers have the potential to become the Sync Primary? At most, this can be equal to the number of iAS machines in your network.

Note that the Sync Primary is not determined by which machine has the highest priority assignment, but rather by which machine you start up first after all servers are installed.

Make sure to note the priority rating you assign to the iAS machines in the cluster. For each installation of iAS in the cluster, you must re-enter the IP address-KXS port number-priority number combination for every the server in the cluster.

It is recommended that you assign the highest priority to the iAS instance you prefer to be the Sync Primary, and that you start that machine up first; assign the next highest priority to the Sync Backup, and to the remaining Sync Alternates in the desired order of promotion.

You do not have to install the servers in the same order as the priority you assign, as long as the priority rating and application server identification information is consistent across each installation.

Post-Installation and Troubleshooting Notes

---

After you install iAS, consider the following issues.

• The iAS user and the web server user must either be the same or from the same group. If the web server is installed as a regular user and the iAS user is installed as the root user, a file permission problem will exist. The web server won't start because it won't have access to the registry file reg.dat.

• After installing iAS, make sure that the iAS gxlib directory (install directory/ias/gxlib) and the registry directory (install directory/ias/registry) are accessible by the web server owner and user.

• Check for required operating system patches. See the readme file for information about how to determine what patches you need.

• 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 iAS 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), iAS hands the request 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.