Previous     Contents     Index     Next     
iPlanet Application Server Installation Guide



Appendix A       Configuring iPlanet Application Server


This appendix explains how to configure iPlanetTM Application Server on Windows and Solaris® 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

  • 9010 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.



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:

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



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:

  • iPlanet Web Server

  • Microsoft Internet Information Server (Windows only)

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:

  1. Check whether or not the iPlanet Application Server 6.5 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.

  2. Stop running your Web Server instance.

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

For information on installing and configuring the Plugin on Apache, see iPlanet Application Server Administrator's Guide.


To Install the Web Connector Plug-in on Solaris

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

  2. Follow the instructions of the installation program.

    For more information on the installation procedure, see Chapter 4 "Easy iPlanet Application Server Installations on Windows".

  3. When prompted, select "iPlanet Servers" as the components to install.

  4. Select Typical as the installation type.

  5. Specify a target installation directory. Do not include spaces in the path name.

  6. When prompted for the components you want to install, choose to install only the iPlanet Application Server.

  7. When prompted to install the iPlanet Application Server components, select the iPlanet Application Server Web Connector Component.

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

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

  2. When prompted, select "iPlanet Servers" as the components to install.

    For more information on the installation procedure, see Chapter 4 "Easy iPlanet Application Server Installations on Windows".

  3. Select Typical as the installation type.

  4. Specify a target installation directory. Do not include spaces in the path name.

  5. When prompted for the components you want to install, select only "iPlanet Application Server 6.5" component.

  6. Click the Change button.

    The iPlanet Application Server subcomponent screen appears.

  7. Select the "Web Connector Plug-in Component" and "Core Server Components" from the list of subcomponents.

  8. Follow the instructions of the installation program.

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

  1. Go to Start >Settings> Control Panel > Administrative Tools > Computer Management

    The Computer Management window will open.

  2. In the left pane, click on the + sign to expand Services and Applications > Internet Information Services > Default Web Site.

  3. Right-click Cgi-bin and select Properties

  4. Select the Virtual Directory tab

  5. Under Applications Settings, click Create.

  6. Select the pull-down menu next to Application Protection.

  7. Select Low(IIS Process)

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

  • <iASInstallDir>\pointbase\client\examples\batch\windows\startconsole

  • <iASInstallDir>\pointbase\client\examples\batch\windows\startcommander

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 iPlanet Application Server Clusters

A simple cluster configuration is demonstrated in the instructions on the iPlanet Developer's Web site. This simplistic cluster configuration is not representative of a true production configuration, but is sufficient to demonstrate the behavior of the iPlanet Application Server.

The configuration consists of two machines that each have a Web server instance and an iPlanet Application Server instance installed. One machine also has a Directory Server instance that is used by the application servers on both machines, as shown in the following illustration.

Figure A-1    A simple iPlanet Application Server cluster configuration

In this simple cluster, configuration data is stored in the directory server on the first machine. When the second application server is installed, it uses the same directory server for configuration information. It's preferable to use the same data tree in the directory server, so that the same configuration information can be shared between all servers and Web connectors.

During installation of the second application server, you must enter the same value for the cluster name and global configuration name as specified during the first application server installation.

In this example, the Web servers are on the same machine as the iPlanet Application Servers. If the Web servers were housed on a separate tier of machines, then you would enter the same global configuration name and cluster name during the Web connector installation. See the iPlanet Application Server Samples for complete instructions on installing and configuring this simple cluster on a Windows or Solaris machine at:


Windows

http://developer.iplanet.com/appserver/samples/cluster/docs/nt-cluster.html


Solaris

http://developer.iplanet.com/appserver/samples/cluster/docs/unix-cluster.html

Note This is not a production configuration. If it were a production configuration, it would most likely have the Web servers on separate machines and a second Directory Server configured to act as a backup for the first Directory Server. For information on how to set up the iPlanet Directory Servers for replication and failover, see the iPlanet Directory Server Installation Guide at: http://docs.iplanet.com



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

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


The following list of installation issues represent the common errors faced during or after installaing iPlanet Application Server.


Before Installation

Before installing iPlanet Application Server, consider the following issues:

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

  • Installation/upgradation will fail on Windows if iPlanet Application Server installables are placed in a directory containing spaces or special characters.

    Ensure that the iPlanet Application Server installables are placed in a directory, which has no spaces or special characters.

  • In custom installation mode, at the point where the user is asked if he wants to populate the Directory Server with entries, if 'None' is chosen then no entry is created.

    After installation, connecting to the server fails since the user is not in the LDAP information.

    Instead of choosing 'None', you should select the 'Suggest' option.

  • Creation of administrator user entry in the remote user directory fails if that directory is read-only.

    The administrator user entry must exist in the user LDAP directory for registering the server through iPlanet Application Server Administration Tool (iASAT).

    To enable iPlanet Application Server to authenticate against a remote user directory server, complete the installation and then perform the following steps:

    1. Create an adminuser.ldif file with the following entries:

      dn: uid=iasadmin., ou=People, o=iplanet.com

      changetype: add

      cn: Nas Administrator

      sn: Nas Administrator

      givenname: iAS admin

      objectclass: top

      objectclass: person

      objectclass: inetorgperson

      ou: People

      uid: iasadmin

      userpassword: password

    2. Run the ladapmodify command:

    ldapmodify iASInstallDir/shared/bin> -D "cn=Directory Manager" -p < ldap_PortNo.> -w <password> -a -f adminuser.ldif.


After Installation

After you install iPlanet Application Server, consider the following issues.

  • A fresh installation of iPlanet Application Server on a Windows machine causes KXS crash.

    Restart the machine after installation.

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


Previous     Contents     Index     Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated March 12, 2002