Release Notes for iPlanet Web Server, Enterprise Edition

Version 4.1 SP8

Updated March 21, 2001




These release notes contain important information available at the time of the Version 4.1 SP8 release of iPlanet Web Server, Enterprise Edition. New features and enhancements, installation notes, known problems, and other late-breaking issues are addressed here. Read this document before you begin using iPlanet Web Server, Enterprise Edition.

An electronic version of these release notes can be found at the iPlanet documentation web site: http://docs.iplanet.com/docs/manuals/. Check the web site prior to installing and setting up your software and then periodically thereafter to view the most up-to-date release notes and manuals.

These release notes contain the following sections:




Who Should Install this Service Pack

For additional details see the Fixed Problems section of these Release Notes.




What's New in iPlanet Web Server, Version 4.1

iPlanet Web Server, Enterprise Edition Version 4.1, includes enhancements described in the following sections:

For a complete list of the iPlanet Web Server Version 4.1 fixed problems, see Fixed Problems.

Creating a JSP Custom Tag Library

iPlanet Web Server 4.1 supports custom JSP tags. This section explains how to create a custom tag library using a working example. The example includes the following directories and files under the document root directory:



/dtds/
   web-jsptaglib_1_1.dtd

/jsps/
   test-tags.jar
   test-tags.jsp


To create the test-tags.jar file, you must create a work area in which you build the tag library and its associated handler classes. This work area contains the following directories and files:



workarea/taglibs/
   ./META-INF:
      taglib.tld
   ./examples:
      ExampleTagBase.class
      ExampleTagBase.java
      FooTag.class
      FooTag.java
      FooTagExtraInfo.class
      FooTagExtraInfo.java
      LogTag.class
      LogTag.java


Both sets of example files are provided with iPlanet Web Server 4.1 in the following directory:

server_root/plugins/samples/servlets/taglibs

Step 1: Create the TLD File

You first need to write a tag library definition (TLD) file outlining the custom tags and their associated handler classes. This TLD file is an XML 1.0 file.

The TLD file must reference an associated DTD file, which has to be named web-jsptaglib_1_1.dtd. This file is available at the iPlanet Web Server website for download. You must make it accessible via a URL in the TLD file (for example http://server:port/dtds/web-jsptaglib_1_1.dtd). An incorrect URL for the DTD file or a corrupt DTD file results in failures in opening your JSPs that contain custom tags.

The tag library must be named taglib.tld and must reside under the META-INF subdirectory in the taglib.jar file you will create in step 4.

Here is an example of a taglib.tld file:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib
PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN"
"http://server:port/dtds/web-jsptaglib_1_1.dtd">

<!-- a tag library descriptor -->

<taglib>
<!-- after this the default space is
"http://java.sun.com/j2ee/dtds/jsptaglibrary_1_2.dtd"
-->

<tlibversion>1.0</tlibversion>
<jspversion>1.1</jspversion>
<prefix>simple</prefix>
<urn></urn>
<info>
A simple tab library for the examples
</info>

<!-- A simple Tag -->
<!-- foo tag -->
<tag>
<name>foo</name>
<tagclass>examples.FooTag</tagclass>
<teiclass>examples.FooTagExtraInfo</teiclass>
<bodycontent>JSP</bodycontent>
<info>
Perform a server side action; uses 3 mandatory attributes
</info>

<attribute>
<name>att1</name>
<required>true</required>
</attribute>
<attribute>
<name>att2</name>
<required>true</required>
</attribute>
<attribute>
<name>att3</name>
<required>true</required>
</attribute>
</tag>

<!-- Another simple tag -->
<!-- log tag -->
<tag>
<name>log</name>
<tagclass>examples.LogTag</tagclass>
<bodycontent>TAGDEPENDENT</bodycontent>
<info>
Perform a server side action; Log the message.
</info>
<attribute>
<name>toBrowser</name>
<required>false</required>
</attribute>
</tag>

</taglib>

If you do not include the DOCTYPE in your taglib.tld file, the JSP compiler throws an exception:

Unable to open taglibrary /jsps/test-tags.jar : com.sun.xml.tree.TextNode

Step 2: Create the Tag Handler Classes

Here is the ExampleTagBase.java file:

package examples;

import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public abstract class ExampleTagBase implements Tag {

public void setParent(Tag parent) {
this.parent = parent;
}

public void setBodyContent(BodyContent bodyOut) {
this.bodyOut = bodyOut;
}

public void setPageContext(PageContext pageContext) {
this.pageContext = pageContext;
}

public Tag getParent() {
return this.parent;
}

public int doStartTag() throws JspException {
return SKIP_BODY;
}

public int doEndTag() throws JspException {
return EVAL_PAGE;
}


// Default implementations for BodyTag methods as well
// just in case a tag decides to implement BodyTag.
public void doInitBody() throws JspException {
}

public int doAfterBody() throws JspException {
return SKIP_BODY;
}

public void release() {
bodyOut = null;
pageContext = null;
parent = null;
}
protected BodyContent bodyOut;
protected PageContext pageContext;
protected Tag parent;
}

Here is the FooTag.java file:

package examples;

import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
import java.util.Hashtable;
import java.io.Writer;
import java.io.IOException;

/**
* Example1: the simplest tag
* Collect attributes and call into some actions
*
* <foo att1="..." att2="...." att3="...." />
*/

public class FooTag
extends ExampleTagBase
implements BodyTag
{
private String atts[] = new String[3];
int i = 0;

private final void setAtt(int index, String value) {
atts[index] = value;
}

public void setAtt1(String value) {
setAtt(0, value);
}

public void setAtt2(String value) {
setAtt(1, value);
}

public void setAtt3(String value) {
setAtt(2, value);
}

/**
* Process start tag
*
* @return EVAL_BODY_INCLUDE
*/
public int doStartTag() {
return EVAL_BODY_TAG;
}
public void doInitBody() throws JspException {
pageContext.setAttribute("member", atts[i]);
i++;
}

public int doAfterBody() throws JspException {
try {
if (i == 3) {
bodyOut.writeOut(bodyOut.getEnclosingWriter());
return SKIP_BODY;
} else
pageContext.setAttribute("member", atts[i]);
i++;
return EVAL_BODY_TAG;
} catch (IOException ex) {
throw new JspException(ex.toString());
}
}
}

Here is the FooTagExtraInfo.java file:

package examples;

import javax.servlet.jsp.tagext.*;

public class FooTagExtraInfo extends TagExtraInfo {
public VariableInfo[] getVariableInfo(TagData data) {
return new VariableInfo[]
{
new VariableInfo("member",
"String",
true,
VariableInfo.NESTED)
};
}
}

Here is the LogTag.java file:

package examples;


import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

import java.io.IOException;

/**
* Log the contents of the body. Could be used to handle errors etc.
*/
public class LogTag
extends ExampleTagBase
implements BodyTag
{
boolean toBrowser = false;

public void setToBrowser(String value) {
if (value == null)
toBrowser = false;
else if (value.equalsIgnoreCase("true"))
toBrowser = true;
else
toBrowser = false;
}

public int doStartTag() {
return EVAL_BODY_TAG;
}

public int doAfterBody() throws JspException {
try {
String s = bodyOut.getString();
System.err.println(s);
if (toBrowser)
bodyOut.writeOut(bodyOut.getEnclosingWriter());
return SKIP_BODY;
} catch (IOException ex) {
throw new JspException(ex.toString());
}
}
}

Step 3: Compile the Tag Handling Classes

Change to your work directory for the java classes (for example workarea/taglibs/examples) and compile the classes, setting the appropriate classpaths. The following command must be all on one line:



/usr/java1.2/bin/javac -classpath java_home/jre/lib/rt.jar:server_root/bin/https/jar/servlets.jar:server_root/bin/http s/jar/jspengine.jar *.java


Step 4: Create the JAR File

From your work directory (for example workarea/taglibs), create a JAR file that contains your taglib.tld file and the class files. Use the following command:

jar cvf ../test-tags.jar .

You should see the following output on the screen:



adding: META-INF/ (in=0) (out=0) (stored 0%)
adding: META-INF/taglib.tld (in=1459) (out=581) (deflated 60%)
adding: examples/ (in=0) (out=0) (stored 0%)
adding: examples/domake (in=235) (out=135) (deflated 42%)
adding: examples/ExampleTagBase.java (in=1123) (out=395) (deflated 64%)
adding: examples/FooTag.java (in=1455) (out=571) (deflated 60%)
adding: examples/FooTagExtraInfo.java (in=426) (out=191) (deflated 55%)
adding: examples/LogTag.java (in=994) (out=450) (deflated 54%)
adding: examples/FooTagExtraInfo.class (in=539) (out=320) (deflated 40%)
adding: examples/ExampleTagBase.class (in=1221) (out=548) (deflated 55%)
adding: examples/FooTag.class (in=1553) (out=784) (deflated 49%)
adding: examples/LogTag.class (in=1249) (out=702) (deflated 43%)


When this is complete, you should see the test-tags.jar file in the workarea directory. Enter the following command to verify this:

ls -ltr test-tags.jar

You should see something like the following output on the screen:

-rw-r--r-- 1 joe staff 7009 May 18 02:37 test-tags.jar

Copy the file to your JSP directory:

cp test-tags.jar jsp_location/jsps

Step 5: Add the JAR File to the Classpaths

Edit the jvm.classpath option in the server_root/https-server_id/config/jvm12.conf file to include the path to the custom tag library file. The following example must be all on one line in the file:

jvm.classpath=java_home/jre/lib/rt.jar:java_home/lib/tools.jar:jsp_location/jsps/test-ta gs.jar

In addition, make sure that your custom tag library file is added to the server classpath along with the regular Java runtime and tools.

Also make sure that the web-jsptaglib_1_1.dtd file is accessible at the URL you specified in the taglib.tld file. Failure to locate this DTD URL results in errors like this in your log files:

Unable to open taglibrary /jsps/test-tags.jar : Unable to open the tag library descriptor: Stream closed.

Step 6: Create the JSP File

This section shows an example JSP file that uses the custom tags. A custom prefix, tt, indicates which tags are handed off to the custom tag library (the foo and log tags).



<%@ page language="java" %>
<%@ taglib prefix="tt" uri="/jsps/test-tags.jar" %>

<title>Testing taglibs </title>

<h1>Testing Jsp taglibs! </h1>

<p><em><tt:foo att1="hello" att2="world" att3="tags" /></em><br>
<p><em><tt:log toBrowser="true" /> Hello Taglibs!</em><br>


Step 7: Test the Custom Tags

Enter the following URL in your browser:

http://server:port/jsps/test-tags.jsp

Your browser should show the following:

Testing Jsp taglibs!

Hello Taglibs!

Storing Multiple Server Certificates on Hardware Tokens

To store multiple server certificates on hardware tokens, perform the following steps:

  1. Create a software trust database even though the web page says you don't need to

  2. Change the nickname of the server when you install it (which violates the webpage telling you not to do this)

  3. Add an undocumented line in the magnus.conf file (via the CERTDefaultNickname directive) for each respective server.

New MaxRqHeaders Directive for magnus.conf File

The default limit for request headers is now 32 entries, and can be adjusted higher as needed by using the MaxRqHeaders nn directive in the magnus.conf file. Note that the request headers cannot be set below 32.

New Platform: Linux Support

iPlanet Web Server, Enterprise Edition Version 4.1 now runs on Linux platforms (with kernel 2.2.12 or later and glibc-2.1.2 or later).

JavaScript and Java Enhancements

iPlanet Web Server, Enterprise Edition Version 4.1 contains the following JavaScript and Java enhancements:

Note: iPlanet Web Server, Enterprise Edition 4.1, does not support Java server-side applets (also called HttpApplets). Use Java servlets instead.

Debugging Servlets with Forte for Java

To set up iPlanet Web Server, Enterprise Edition 4.1 so you can use the Forte for Java debugger, follow these steps:

  1. If you have not already done so, install the JDK version 1.2.x that iPlanet Web Server requires as described in the Programmer's Guide to Servlets. The specific version you need depends on your platform.

  2. Install the JDK version 1.3, available here:

    http://java.sun.com/j2se/1.3/

    Although iPlanet Web Server uses the JDK version 1.2.x, Forte for Java requires version 1.3.

  3. Install Forte for Java, Community Edition 1.0, available here:

    http://www.sun.com/forte/ffj/ce/

  4. iPlanet strongly recommends that you also install the JPDA, available here:

    http://java.sun.com/products/jpda/

  5. If you installed the JPDA, copy all the files from the jpda_install/bin directory to the jdk1.2_install/jre/bin directory. Also copy the jpda.jar file from the jpda_install/lib directory to the jdk1.2_install/jre/lib/ext directory.

    Note that the JPDA runs on JDK 1.2, not 1.3.

  6. On Windows NT, add the following line to the obj.conf file to enable the NT console:

    Init fn="nt-console-init" stdout=console stderr=console

  7. Edit the jvm12.conf file to enable remote debugging. If you did not install the JPDA, add the following lines:

    jvm.enableDebug=1
    jvm.compiler=NONE
    jvm.printErrors=1

    If you installed the JPDA, add the following lines:

    jvm.enableDebug=1
    jvm.compiler=NONE
    jvm.printErrors=1
    jvm.option=-classic
    jvm.option=-Xnoagent
    jvm.option=-Xrunjdwp:transport=dt_socket,server=y,suspend=n

  8. Start Forte for Java, and mount the directory that contains the servlet you want to debug.

  9. Start iPlanet Web Server. You will see a line similar to the following displayed in the console:

    Listening for transport dt_socket at address: port_number

    Write down this port_number.

  10. In Forte for Java, select the Debug menu and the Attach to VM... option. Enter the port_number in the Port: text box, then select OK.

You are now ready to debug your servlet.

Performance Enhancements

perfdump Output Changed

The following information no longer appears in the perfdump output:

SessionCreationInfo:
------------------
Total Sessions Created 48/1224
Sessions In Free List 0
Active Sessions From Free List 0

The Sessions In Free List and Active Sessions From Free List entries have been removed because the way threads are reclaimed in the server has been changed. The entry has been moved to the following section of the perfdump output:

ListenSocket #0:
------------------
Address https:\\INADDR_ANY:80
ActiveThreads 48
WaitingThreads 47
BusyThreads 1
Thread limits 48/512
Total Sessions 48/712

The ActiveThreads, WaitingThreads, BusyThreads, and Thread limits entries have not changed.

The Total Sessions entry used to be Total Sessions Created. The maximum value is now much lower (RqThrottle + KAPool). The way iPlanet Web Server, Enterprise Edition version 4.1 frees threads has been streamlined to improve server performance, especially on heavily loaded sites (>12K hits per minute).

When the server hits its RqThrottle + KAPool limits (712 in this case), an error is entered into the errors log as follows:

[date][pid] The server has created it configured maximum number of threads, %d.

This error is generated once in the lifetime of a process, and is generated for each child process if MaxProcs is greater than 1.

Reaching the maximum number of configured threads is not necessarily undesirable, and you need not automatically increase the number of threads in the server. More does not always mean better. Reaching this limit only means that the server needed this many threads at some moment (at peak load), but as long as it was able to serve requests in a timely manner, the server is adequately tuned. If you check your perfdump output on a regular basis and notice that BusyThreads is often near the RqThrottle maximum, you should consider increasing your thread limits.

Security Enhancements

iPlanet Web Server, Enterprise Edition 4.1, includes security enhancements described in the following sections:

FORTEZZA Support

iPlanet Web Server, Enterprise Edition 4.1, includes FORTEZZA encryption support.



Note

SSL client authentication requires that the certificate authority that issued the client certificate is trusted by the server. Previous versions of Netscape FORTEZZA servers would automatically trust the PAA from the server's FORTEZZA card for client operations. In the 4.x servers, this does not occur. Instead, the administrator needs to install the PAA certificate as a trusted client authentication certificate authority.



New Support for Key Database Passwords in password.conf File

By default, the web server prompts the administrator for the key database password before starting up. If you want the web server to be able to restart unattended, you need to save the password in a password.conf file. Be sure that your system is adequately protected so that this file and the key databases are not compromised.

To configure the password, create a new password.conf file in the config subdirectory of the server instance. If you are using the internal PKCS#11 software encryption module that comes with the server, Enter in the following information:

Communicator Certificate DB : yourpassword

If you are using a different PKCS#11 module, for example for hardware encryption or hardware accelerators, you will need to specify the name of the PKCS#11 module, followed with the password. For example:

nFast: yourpassword

Miscellaneous Information




Required Patches

Required patches are listed for the following platforms:

Sun Solaris Patches

The following patches are recommended for Solaris users of iPlanet Web Server, Enterprise Edition Version 4.1. In addition, you should have the patches in Sun's recommended patch list. For Sun's recommended patch list, see http://sunsolve.sun.com/pubpatch. To get Sun patches, see your Sun service provider.

For each patch, use the listed revision or a higher revision. For example, if you need patch 111111-01, the later revision 111111-03 will also work.

Note that if you are using a JDK, you may need additional patches.

Solaris 2.6

The following patches are the recommended patches for users running iPlanet Web Server, Enterprise Edition 4.1, on Solaris 2.6:

Solaris 7

The following patches are recommended for users running iPlanet Web Server, Enterprise Edition 4.1 on Solaris 7:

Compiler Patches for Solaris

The following Solaris patches are recommended for people using compilers:

HP Patches

The following patches are recommended for HP users of iPlanet Web Server, Enterprise Edition 4.1. In addition, you should have the patches in HP's recommended patch list. For HP's recommended patch list, see http://us-support.external.hp.com/index.html/.

Compaq Tru64 Patches

The following patches are recommended for Compaq Tru64 users of iPlanet Web Server, Enterprise Edition Version 4.1:

Windows NT Service Packs

Requires Windows NT 4.0, with Service Pack 6.




Installation, Upgrade, and Migration Information

This section includes information for installing, upgrading, and migrating your iPlanet Web Server. For additional information about system requirements and installing the product, see the Installation and Migration Guide.

The following table summarizes the supported platforms for iPlanet Web Server. All platforms require 64 MB memory and 150 MB disk space.



Table 2    iPlanet Web Server 4.1 Supported Platforms

Vendor

Architecture

Operating System

Compaq 

Alpha 

Tru64 4.0d, 4.0e*, 4.0f* 

Hewlett-Packard 

PA-RISC 

HP-UX 11.0, 11.0 64-bit* 

Silicon Graphics** 

MIPS 

SGI IRIX 6.5.6 

Sun 

SPARC 

Solaris 2.6, 7*, 8 

Intel 

Pentium 

Windows NT 4.0 

RedHat 

x86 

Linux 2.2.12 with glibc 2.1.2 (RedHat 6.1) 

IBM 

Power PC 

IBM AIX 4.3.3 

* Supported via binary compatibility

** SGI does their own port and makes the Web Server available separately.

In addition, this section includes the following information:

Silent Installation (Unix and Linux)

If you want to install several iPlanet Web Servers, you can use silent installation to create a file of responses to the setup program's prompts. You can then edit the file, install.inf, and use it to install future iPlanet Web Server installations. Silent installation works best when you use the Typical installation and your installations are all similar.



Note

Silent installation does not work on Windows NT.





Caution

The install.inf file contains the password used to log on to the Administration server. The password is not encrypted; it is in plain text. If you use silent installation, be sure and delete the install.inf file once you are through with it.



To use silent installation, follow these steps:

  1. Run setup with the -k option, which creates a file called install.inf that contains all your responses to the installer's prompts. At the command prompt, enter:

    ./setup -k

  2. Answer the installer prompts and install iPlanet Web Server.

  3. When the server is installed, go to the server_root/setup directory, where you'll find the install.inf file.

  4. Copy the install.inf file to the directory where you will run setup to install your next iPlanet Web Serve.

  5. Edit the values in the install.inf file to match the values of the next server you want to install. For example, change the machine name, port number, installation directory, etc.

  6. Run setup using the install.inf file for input. For example:

    ./setup -s -f install.inf

The server is installed.

The following is an example of an install.inf file.

[General]
FullMachineName= austen.iplanet.com
SuiteSpotUserID= annh
SuitespotGroup= staff
SecurityCheck= False
RequireDomain= False
ServerRoot= /usr/netscape/server4
Components= WebServer

[WebServer]
Upgrade= False
Reinstall= False
AdminPort= 8888
HttpPort= 1888
HttpDocRoot= /usr/netscape/server4/docs
AdminSysUser= annh
AdminName= admin
AdminPassword= password
UgLdapUse= Yes
UgLdapUrl= ldap://test:389/o=siroe.com
UgLdapName= cn=Directory Manager
UgLdapPassword= password
JRE_DIR= /usr/netscape/server4/bin/https/jre
USE_JDK= No
CompVersions= 2:2:1:2:0:0:0:0:0:
Components= nescore,JRE,java,cleanup

[cleanup]
Archive= cleanup.zip

The following table shows some useful install.inf parameters to edit. For best results, do not edit any parameters except those listed in the table.



Table 3    install.inf Parameters

Parameter Name

Description/Use

FullMachineName 

The machine name. 

SuiteSpotUserID 

The user ID used when running the default instance of the iPlanet Web Server. 

SuiteSpotGroup 

The group the user running the default instance of the iPlanet Web Server belongs to. 

ServerRoot 

The directory where you install the server. 

AdminPort 

The Administration Server port. 

HttpPort 

The port of the default iPlanet Web Server instance. 

HttpDocRoot 

The document root of the iPlanet Web Server instance. 

AdminSysUser 

The Unix user ID used when running the Administration Server. 

AdminName 

The user name used to access to the Administration Server's administration screens. 

AdminPassword 

The password used to access to the Administration Server's administration screens. 

UgLdapUse 

Yes and No indicate whether you are using the LDAP Directory Server. 

UgLdapUrl 

The LDAP URL of the Directory Server you are using. 

UgLdapName 

The Bind DN of the Directory Server you are using. 

UgLdapPassword 

The Directory Server password. 

JRE_Dir 

If you are installing the JRE shipped with the iPlanet Web Server, the directory where it is installed. 

USE_JDK 

Yes and No indicate whether you are using a JDK. 

JDK_DIR 

The directory where your JDK is installed. 

RequireDomain 

Indicates whether a domain name is required for installation. If this directive is not present, the value True is assumed and a domain name is required. 

SecurityCheck 

Indicates whether version, dependency, and security level (export/domestic) compatibility within the server root are checked. If this directive is not present, the value True is assumed. 

Installation Issues


Problem 383924. Subcomponent Installation

If you do not install all subcomponents when you initially install the server, then later install them, the following situations occur:


Problem 387172 (Linux/Unix). Installing Another 4.x Server in the Same Directory

If you install another 4.x server (for example, Netscape Directory Server or Messaging Server) in the same directory as iPlanet Web Server, follow these steps when uninstalling:

  1. Copy the uninstall script (uninstall) to another file, for example, uninstslapd

  2. Use uninstall to uninstall iPlanet Web Server.

  3. Rename uninstslapd to uninstall

  4. Use uninstall to uninstall Directory Server 4.1.


Problem 386834, 388194 (Windows NT). Installing Directory or Messaging Server and Web Server on the Same Machine

If you install both Netscape Directory or Messaging Server and iPlanet Web Server on the same machine, during the web server installation when you are asked which version of libraries to install, always select those which have the most recent release dates, except for system32\libplc.dll. If you install both servers in the same directory, you should have no problems uninstalling any server.


Workaround

If you install the servers in different directories, you need to uninstall iPlanet Web Server first, and preserve a copy of a DLL file before uninstalling, as shown in the following steps:

  1. Copy NSLDAP32V40.DLL to a temporary directory.

  2. Uninstall iPlanet Web Server.

  3. Copy NSLDAP32V40.DLL back to the directory where Directory Server is installed.

  4. Uninstall Directory Server.


Problem 386464. Default Encryption Settings

The default encryption settings on the Encryption Preferences page may not accurately reflect the actual settings in magnus.conf.


Workaround

To correct this, go to the Encryption Preferences page, select the ciphers you want to use, and click Save and Apply to update the settings in magnus.conf.


Problem 388306. Installation of iPlanet Web Server 4.1 Subcomponents

If you do not install all subcomponents when you initially install the server, then install a subcomponent that depends upon other subcomponents, then run the installer again, the subcomponents on which the installed subcomponent depends may be shown as not installed, when they are in fact installed.

For example, if you install the JRE and Server-Side JavaScript Database components, the next time you run the installer the Java, Servlets, and Server-Side JavaScript subcomponents are shown as not installed. These subcomponents were installed previously, however, because the Server-Side JavaScript Database component depends on them.


Problem 409342. Installation of ES 4.1sp2 on NT over an old instance of server gives error message

When trying to install ES4.1sp2 over an old instance of the server on NT, the installation program says that the user must first remove the old configuration directories.

Uninstall Issues


Problem 386838. Uninstall on NT gives an error and leaves libnspr3.dll, msvcrt.dll

After uninstalling the web server on NT, an error appears: "Can't delete some files." Certain files are not removed from the system.


Problem 385770 (Unix). Obsolete 4.0 Server Files Not Deleted During Uninstall After Upgrade to Version 4.1

On Unix, when you upgrade the iPlanet Web Server from version 4.0 to 4.1, and then uninstall the upgraded server, files present in version 4.0 only are not uninstalled. This problem occurs only for upgrading and uninstalling the iPlanet Web Server, not for installing and uninstalling it.


Workaround

After uninstalling the upgraded server, manually delete the following files if they are present:

/bin/https/admin/html/index.lst
/bin/https/admin/html/rmhttp.html
/bin/https/admin/html/sec-activate.properties
/bin/https/admin/html/sec-mgcrt.html
/bin/https/admin/html/status.html
/bin/https/httpadmin/bin/nsesvars
/bin/https/httpadmin/html/index.lst
/bin/https/httpadmin/html/nsesvars.html
/bin/https/httpadmin/html/sec-mgcrt.html
/bin/https/httpadmin/html/sitemon.html
/bin/https/install/misc/de/index.def
/bin/https/install/misc/es/index.def
/bin/https/install/misc/fr/index.def
/bin/https/install/misc/ja/inxex.def
/bin/https/jar/jsp.jar
/bin/https/jar/NSServletTools.jar
/bin/https/jar/swingall.jar
/bin/https/jar/xm14j_1_1_9.jar
/bin/https/lib/libadminutil.so
/manual/https/nsapi/00-prefa.htm
/manual/https/nsapi/bklast.htm
/manual/https/pg/bklast.htm
/manual/https/servlets/2-examp.htm
/manual/https/servlets/bklast.htm
/manual/https/servlets/g-apifix.htm
/manual/https/servlets/jsp092/images/banner.gif
/manual/https/servlets/jsp092/images/beancycle.jpg
/manual/https/servlets/jsp092/images/beans.jpg
/manual/https/servlets/jsp092/images/constructor-index.gif
/manual/https/servlets/jsp092/images/contructors.gif
/manual/https/servlets/jsp092/images/method-index.gif
/manual/https/servlets/jsp092/images/methods.gif
/manual/https/servlets/jsp092/images/pagecycle2.jpg
/manual/https/servlets/jsp092/images/red-ball-small.gif
/manual/https/servlets/jsp092/images/red-ball.gif
/manual/https/servlets/jsp092/images/scenario2.jpg
/manual/https/servlets/jsp092/images/smi.logo.gif
/manual/https/servlets/jsp092/images/yellow-ball-small.gif
/manual/https/servlets/jsp092/images/yellow-ball.gif
/manual/https/servlets/jsp092/jsp092.html
/plugins/lib/libnsrwdb.so
/plugins/lib/libnsrwdb2.so
/plugins/lib/libnsrwifx.so
/plugins/lib/libnsrwora.so
/plugins/lib/libnsrwsyb.so
/plugins/samples/js/oldvideo/*
/plugins/samples/servlets/edemo/*
/plugins/samples/servlets/jsp/*
/wai/*

Upgrade Issues


Problem 524885. Installing an iPlanet Web Server 4.1 SP release disables WebPublishing.

When you install an iPlanet Web Server 4.1 SP release over an existing iPlanet Web Server 4.1 installation, WebPublishing is disabled.


Workaround

  1. Before installing the iPlanet Web Server 4.1 SP release, make a backup of the file server_root/https-server_name/search/admin/dblist.ini.

  2. Install the SP release in the directory where your existing iPlanet Web Server 4.1 is installed.

  3. Replace the dblist.ini file in your installation with your backup copy.

  4. Start your upgraded server.


Problem 385762. Upgrading From Web Server 4.0 with Your Own JDK

If you are upgrading from iPlanet Web Server 4.0 and using your own JDK, you need to edit the start-jvm file, which is in server_root/https-admserv. Add the following information (note that you need to add the second line of code on a single line in start-jvm):

NSES_JDK=path_to_jdk; export NSES_JDK

NSES_JDK_RUNTIME_CLASSPATH=${NSES_JRE}/lib/ext/iiimp.jar:${NSES_JRE}/lib/i18n.jar :${NSES_JRE}/lib/rt.jar:${NSES_JRE}/lib/tools.jar:${NSES_JDK}/lib/dt.jar;export NSES_JDK_RUNTIME_CLASSPATH


Problem 384875. Upgrading WAI Component from 4.0 to 4.1

If you upgrade the iPlanet Web Server from version 4.0 to 4.1 and you have WAI installed, you see the following error message when the WAI component is upgraded:

ERROR: ORB directory not specified in installation script [/var/tmp/aaasuaW9b] ERROR. Failure installing WAI support. Do you want to continue [n]?

Enter y to continue. The WAI component will be installed properly despite the error message.


Problem 387718. Upgrading to iPlanet Web Server 4.1 Server Fails to Add res Directory and cjava.properties and sjava.properties Files

When you upgrade iPlanet Web Server on NT, the res directory and its contents are missing in the server instances.


Workaround

Create the server_root/https-instance/config/res directory, then create ASCII files named cjava.properties and sjava.properties. The contents of these files must be as follows:

Contents of cjava.properties:

# C++ messages

servlets.src.nsapi.ERR_JVM_LOAD = Failure to load JVM (check your JRE)
servlets.src.nsapi.ERR_UTILITY_CLASSES = Internal error: Unable to initialize utility classes
servlets.src.nsapi.ERR_CLASS_LOOKUP = Internal error: Unable to locate class: %s
servlets.src.nsapi.ERR_METHODS_LOOKUP = Internal error: Unable to find required methods in Java classes
servlets.src.nsapi.ERR_REGISTER_METHODS = Internal error: Failure registering native methods for the JVM
servlets.src.nsapi.ERR_OBJECT_CREATE = Internal error: Unable to create Java object: %s
servlets.src.nsapi.ERR_OBJECTS_CREATE = Internal error: Unable to create one or more Java objects (possibly running out of heap)
servlets.src.nsapi.ERR_NATIVE_THREAD = One or more NSServlet functions were not configured to be running on a native thread (check your obj.conf)
servlets.src.nsapi.ERR_NAMETRANS = Object name is missing in NameTrans (check your obj.conf)
servlets.src.nsapi.ERR_SERVLETS_MKDIR = Unable to create directory %s (required by the servlet subsystem)
servlets.src.nsapi.ERR_JSPCACHE_CLEANUP = Unable to create/cleanup jsp class cache
servlets.src.nsapi.ERR_OUTOFMEMORY = Internal error: unable to allocate space from pool (%s)
servlets.src.nsapi.ERR_SEMCREATE = Internal error: failure to create semaphores
servlets.src.nsapi.ERR_SESSIONCACHE_CLEANUP = Unable to create/cleanup persistent session data cache

util.src.ERR_EXCEPTION = Internal error: Unexpected Java exception thrown (%s,%s), stack: %s
util.src.ERR_FINDTHROWABLE = Internal error: unable to locate: %s
jvm.src.ERR_JVM_ATTACH = Internal error: Unable to attach to the JVM
jvm.src.ERR_JVM_DETACH = Internal error: Unable to detach from the JVM
jvm.src.ERR_JVM_READCFGFILE = Error reading JVM config file (%s)
jvm.src.ERR_JVM_EXITING = Exiting JVM
jvm.src.ERR_JVM_ABORTING = Aborting JVM
jvm.src.ERR_JVM_EXITING_ON_ABORT = Exiting JVM due to: jvm_abort () and jvm.exitOnAbort > 0
jvm.src.ERR_JVM_EXITING_ON_LOOP = Exiting JVM due to: infinite loop detected in the JVM signal handler
jvm.src.ERR_JVM_CLASSPATH = JVM ClassPath=%s
jvm.src.ERR_JVM_BADPROFILER = Unknown profiler: %s
jvm.src.ERR_JVM_BADPARAM = JVM config: unrecognized parameter (%s)
jvm.src.ERR_JVM_SINGLEPROCESS = No profiling or debugging is allowed in multi-process mode (disabled)
jvm.src.ERR_JVM_PROFILERCLASS = Unable to locate OptimizeIT Audit class
jvm.src.ERR_JVM_PROFILERMETHODS = Unable to locate OptimizeIT Audit class methods
jvm.src.ERR_JVM_PROFILERSTART = Attempt to start OptimizeIT failed (exception: %s,%s)
jvm.src.ERR_JVM_PROFILERSTARTED = OptimizeIT profiler lanched
jvm.src.ERR_JVM_DIFFCONFIG = JVM config: Use configuration file properties to specify this parameter (%s)
jvm.src.ERR_JVM_CREATE = Internal error: unable to create JVM
jvm.src.ERR_JVM_EXISTS = JVM instance has already been created within the process, numVMs=%d
jvm.src.ERR_JVM_EXIT_STATISTICS = JVM exit statistics: AttachedThreads/Max=%u/%u, ActiveThreads/Max=%u/%u

Contents of sjava.properties:

# Server-side Java properties (primarely may be used for internationalization)

servlet.NSServletEntity.msg_unable2findClass = Unable to locate class: %1 (%2)
servlet.NSServletEntity.msg_exceptionInitFunc = Internal error: unexpected exception thrown from the servlet init function (servlet class=%1): %2, Stack: %3

servlet.NSServletEntity.msg_exceptionNewInstance = Internal error: newInstance failed (servlet class=%1): %2
servlet.NSServletEntity.msg_exceptionInitThrown = Internal error: servlet init function had trown ServletException (servlet class=%1): %2
servlet.NSServletEntity.msg_jspCompileFailed = JSP compilation error: %1, stack: %2
servlet.NSServletEntity.msg_recompilingJSPFile = recompiling JSP file: %1

servlet.NSServletWrapper.msg_exceptionDestroyFunc = Internal error: unexpected exception thrown from the servlet destroy function (servlet class=%1): %2, Stack: %3

servlet.NSServletRunner.msg_wrongSeviceFuncParam = Internal error: service function recieved wrong parameters
servlet.NSServletRunner.msg_exceptionServiceFunc = Internal error: exception thrown from the servlet service function (uri=%1): %2, Stack: %3

servlet.NSServletRunner.msg_missingObjectType = Internal error: ObjectType is missing
servlet.NSServletRunner.msg_wrongObjectType = Internal error: ObjectType has incorrect value - magnus-internal/servlet|jsp expected
servlet.NSServletRunner.msg_infoLoadServet = Internal Info: loading servlet %1
servlet.NSServletRunner.msg_exceptionInitFunc = Internal error: exception thrown from the servlet init function (servlet=%1): %2
servlet.NSServletRunner.msg_exceptionClassNotFound = Internal error: Class %1 not found (servlet=%2):

servlet.NSServletRunner.msg_exceptionLoadServletFailed = Internal error: Failed to load servlet (servlet=%1)

servlet.NSServletRunner.msg_exceptionFindClassName = Internal error: Could not figure out the class name (uri=%1, SCRIPT_NAME=%2)
servlet.NSServletRunner.msg_exceptionFindContext = Internal error: Could not find specifed servlet context (context=%1)
servlet.NSServletRunner.msg_exceptionGetServlet = Internal error: Failed to get GenericServlet. (uri=%1,SCRIPT_NAME=%2)
servlet.NSServletRunner.msg_unable2findServlet = Internal error: unable to locate servlet (%1) by name (probably a configuration error)
servlet.NSServletRunner.msg_fileNotFound = requested file not found (uri=%1, filename=%2)
servlet.NSServletRunner.msg_regexpMarkError = Bad regular expression: %1

servlet.NSServletRunner.msg_sessionMgrNotFound = SessionManager class not found (%1): loading default one
servlet.NSServletRunner.msg_sessionMgrFailure = Unable to instatiate SessionManager class (%1, exception=%2): initializing default one
servlet.NSServletLoader.msg_classSecurity = NSServletLoader: security violation loading class (%1)

session.MMapSession.mgs_unable2Retrieve = Session Manager: unable to retrieve the object (%1)
session.MMapSession.mgs_unable2Store = Session Manager: unable to store the object (%1)
session.MMapSessionManager.msg_sessionType = MMapSessionManager: can manage only MMapSessions

session.SimpleSessionManager.msg_limitReached = SimpleSessionManager: cannot create a new session as the limit on maximum number of sessions has already been reached: (%1)
session.SimpleSessionManager.msg_sessionType = SimpleSessionManager: can manage only SimpleSessions
session.SimpleSessionManager.msg_maxSessionsNotValid = SimpleSessionManager: maximum number of sessions should be an integral number; using a default value (%1)
session.SimpleSessionManager.msg_timeoutNotValid = SimpleSessionManager: session timeout value should be an integral number; using a default value (%1)

session.SimpleSessionManager.msg_simpleSessionManagerDefaultInit = SimpleSessionManager: Default values for maximum number of sessions is %1 with a time out value of %2 seconds
session.SimpleSessionManager.msg_simpleSessionManagerUnbindError = SimpleSessionManager: Failed to call unbind method on an object bound to the session by name (%1) due to %2
session.SimpleSessionManager.msg_simpleSessionManagerInit = SimpleSessionManager: Maximum number of sessions (%1) with a time out value of (%2) seconds

session.JdbcSessionManager.msg_sessionType = JdbcSessionManager: can manage only JdbcSessions
session.JdbcSessionManager.msg_timeoutNotValid = JdbcSessionManager: session timeout value should be an integral number; using a default value (%1)
session.JdbcSessionManager.msg_poolNotValid = JdbcSessionManager: specified pool (%1) size is not valid, will using default value
session.JdbcSessionManager.msg_jdbcSessionManagerInit = JdbcSessionManager: initialized with timeOut=%1, url=%2, driver=%3
session.JdbcSessionManager.msg_jdbcSessionManagerFailed = JdbcSessionManager: initialization failed: %1
session.JdbcSessionManager.msg_sessionsReaped = JdbcSessionManager: %1 session(s) had expired and removed
session.JdbcSessionManager.msg_unable2Store = JdbcSessionManager: unable to serialize the object (%1)
session.JdbcSessionManager.msg_unable2Retrieve = JdbcSessionManager: unable to retrieve the object (%1)
session.JdbcSessionManager.msg_exceptionThrown = JdbcSessionManager: exception occured while %1: session id=%2, exception: %3

servlet.NSRequestDispatcher.msg_invalidReqResClass = ServletRequest/Response classes passed into RequestDispatcher must be NSHttpRequest/Response classes
servlet.NSRequestDispatcher.msg_includeFailed = RequestDispatcher: include call failed
servlet.NSRequestDispatcher.msg_forwardFailed = RequestDispatcher: forward call failed

servlet.NSServletAdmin.msg_badServlet = Config: servlet entry is incorrect or incomplete (%1)
servlet.NSServletAdmin.msg_uknownServlet = Config: on-startup loaded servlet does not exist (%1)
servlet.NSServletAdmin.msg_badAlias = Config: alias entry is incomplete or refers to a non-existing servlet (%1)

jsp.JSPCompiler.msg_noSuchBuffer = Internal error: unable to find JSP buffer %1
jsp.JSPCompiler.msg_compileError = Java/JSP compile error: %1
jsp.JSPCompiler.msg_javacNotThere = Java compiler or classpath is not set up properly

jsp.JSP.msg_badScriptletTag = JSP parse error (line %1) - Incomplete scriptlet tag
jsp.JSP.msg_badTagEnding = JSP parse error (line %1) - Incomplete tag ending of %2
jsp.JSP.msg_compileError = Unknown compile error %1
jsp.JSP.msg_badLanguage = JSP parse error (line %1) - unknown language

jsp.JSPTree.msg_badTag = JSP parse error - %1 tag is invalid
jsp.JSPTree.msg_badSetterType = JSP parse error - invalid bean setter type

jsp.JSPTree.msg_unknownSSI = JSP parse error - unrecognized command in SSI statement: %1
jsp.JSPTree.msg_unknownTagValue = JSP parse error - unrecognized value for %1 tag: %2

jsp.JSPTokenizer.msg_unexpectedEOF = JSP parse error - unexpected end of file

servlet.admin.Sam.msg_noNSHOME = NS_SERVER_HOME property must be defined!
servlet.admin.Sam.msg_badNSHOME = NS_SERVER_HOME is invalid!
servlet.admin.Sam.msg_noServers = No Enterprise Server instances found!
servlet.admin.Sam.msg_serverNotFound= Server not found (%1)
servlet.admin.Sam.msg_badParam = Bad or insufficient parameters to perform command (%1)
servlet.admin.Sam.msg_notExists = Servlet was not found (%1)
servlet.admin.Sam.msg_alreadyExists = Servlet already exists (%1)
servlet.admin.Sam.msg_cannotCreate = Unable to create servlet (%1)
servlet.admin.Sam.msg_listServers = Available server instances:

servlet.admin.SamPanel.HEIGHT = 500
servlet.admin.SamPanel.WIDTH = 700
servlet.admin.SamPanel.title = Servlet Application Manager
servlet.admin.SamPanel.logoIcon = icons/enterprise.gif

servlet.admin.SamPanel.quitTitleMessage = Quiting Sam?

servlet.admin.SamPanel.quitMessage = Changes have been made\nSave?
servlet.admin.SamPanel.menu_File = File
servlet.admin.SamPanel.menu_FileKeey= f
servlet.admin.SamPanel.mb_About = About Sam ...
servlet.admin.SamPanel.mb_Exit = Exit
servlet.admin.SamPanel.mb_ExitKey = e

servlet.admin.ObjDirPanel.l_nsapiFunc = NSAPI function

servlet.admin.ObjDirPanel.b_apply = Apply
servlet.admin.ObjDirPanel.b_restore = Restore

servlet.admin.ObjDirPanel.b_remove = Remove
servlet.admin.ObjDirPanel.t_border = Arguments

servlet.admin.ServletPanel.l_servlet = Servlet
servlet.admin.ServletPanel.l_className = ClassName
servlet.admin.ServletPanel.l_classPath = ClassPath
servlet.admin.ServletPanel.cb_startup = load on startup
servlet.admin.ServletPanel.b_apply = Apply
servlet.admin.ServletPanel.b_restore = Restore
servlet.admin.ServletPanel.b_remove = Remove
servlet.admin.ServletPanel.b_browse = Browse
servlet.admin.ServletPanel.t_border = Initial Arguments
servlet.admin.ServletPanel.l_border = Aliases
servlet.admin.ServletPanel.fc_title = Choose ClassPath directory

servlet.admin.ServletConfigPanel.l_docRoot = Servlets docRoot

servlet.admin.ServletConfigPanel.l_reloadInterval = Reload Interval

servlet.admin.ServletConfigPanel.b_apply = Apply
servlet.admin.ServletConfigPanel.b_restore = Restore


Problem 388075. Upgrade to iPlanet Web Server 4.1 Does Not Update the obj.conf admin-check-admpw Setting

When you upgrade the iPlanet Web Server to version 4.1, the admin-check-admpw function in the Administration Server's obj.conf file includes the parameter final=false, when it should include final=true. This problem occurs only for upgrading the iPlanet Web Server, not for installing it.


Workaround

After upgrading, edit the admin-check-admpw function in the server_root/https-admserv/config/obj.conf file to change final=false to final=true.


Problem 388076. Upgrade to iPlanet Web Server 4.1 Fails to Update mime.types File Correctly

When you upgrade the iPlanet Web Server to version 4.1, the mime.types files for the Administration Server and the server instances have missing or incorrect information. This problem occurs only for upgrading the iPlanet Web Server, not for installing it.


Workaround

After upgrading, edit the mime.types files in server_root/https-admserv/config and server_root/https-instance/config to change the following line:

type=application/x-pointplus exts=css

to the following lines:

type=text/css exts=css
type=image/x-icon exts=ico


Problem 387908. Upgrade Does Not Modify magnus.conf File

When you upgrade the iPlanet Web Server to version 4.1, information is missing from the Administration Server's magnus.conf file. This problem occurs only for upgrading the iPlanet Web Server, not for installing it.


Workaround

After upgrading, verify that the following line is present in the server_root/https-admserv/config/magnus.conf file, and that it includes the ${NSES_JRE_RUNTIME_LIBPATH} part:

ExtraPath server_root/bin/https/bin;${NSES_JRE_RUNTIME_LIBPATH}

The following line is optional but recommended. It limits the number of threads used by the Administration Server.

RqThrottleMinPerSocket 4

Migration Issues


Problem 393139. Migrating Server with Encryption On Makes Server Settings Inaccessible

If you migrate the server with encryption turned on and then click the View Server Settings button on the Preferences tab, you see the following message:

Internal Error. The administration server was unable to fulfil your request.


Workaround

Migrate the server with encryption turned off.


Problem 393221. Configuration Styles May Not Migrate Correctly

Configuration styles may not migrate correctly from Netscape Enterprise Server 3.6 to iPlanet Web Server 4.1. Double-check your configuration style settings after migration. Change this line:

ObjectType fn=type-by-exp exp="*.(class|jar)" type=magnus-internal/servlet

to look like this:

ObjectType fn="force-type" type="magnus-internal/servlet"




Fixed Problems

This section describes the problems that have been fixed in service pack releases.

iPlanet Web Server, Enterprise Edition 4.1 SP8

iPlanet Web Server, Enterprise Edition 4.1 SP8 includes the following bug fixes:

iPlanet Web Server, Enterprise Edition 4.1 SP7

iPlanet Web Server, Enterprise Edition 4.1 SP7 includes the following bug fixes:

iPlanet Web Server, Enterprise Edition 4.1 SP6

iPlanet Web Server, Enterprise Edition 4.1 SP6 includes the following bug fixes:

iPlanet Web Server, Enterprise Edition 4.1 SP5

iPlanet Web Server, Enterprise Edition 4.1 SP5 includes the following bug fixes:

iPlanet Web Server, Enterprise Edition 4.1 SP4

iPlanet Web Server, Enterprise Edition 4.1 SP4 includes the following bug fixes:

iPlanet Web Server, Enterprise Edition 4.1 SP3

iPlanet Web Server, Enterprise Edition 4.1 SP3 includes the following bug fixes:

iPlanet Web Server, Enterprise Edition 4.1 SP2

iPlanet Web Server, Enterprise Edition 4.1 SP2 includes the following bug fixes:

iPlanet Web Server, Enterprise Edition 4.1 SP1

iPlanet Web Server, Enterprise Edition 4.1 SP1 includes the following bug fixes:




Known Problems and Solutions

This section lists known problems with this release of iPlanet Web Server, Enterprise Edition 4.1. Information is organized into the following areas:

General


invoking Netscape browser from the Directory Console

Installation Guide does note specify that you must include Netscape Browser in your $PATH or Path. Consequently, the Web Admin Application is not launched.


Workaround

Add Netscape Browser to your $PATH or Path.


Do not run CGIs using Perl 5.6.x with the -w flag

If you run a CGI using perl 5.6.x with the -w flag, the Web Server returns an error message, such as:

cgieng_scan_headers reports: the CGI program foo.pl did not produce a valid header (name without value: got line "can't ignore signal chld, forcing to default.")


Workaround

Instead, include the following code in the file:

use warnings;


Bug in the Tru64 Unix 4.0d Kernel Causes the Kernel to Crash

There is a bug in the Tru64 Unix Unix 4.0d kernel which causes the kernel to crash under some stressed conditions with file cache in the Web Server. Currently, the patch kit 6 is the latest one for 4.0d kernel. A future OS patch kit will correct this problem.


Workaround

Meanwhile, to avoid this problem, add the following entry to the /etc/sysconfigtab file and reboot the system:

vm: vm-map-index-enabled=0


Problem 44812 (Windows NT only). Windows NT iPlanet Web Server Cannot Find Files on Remote-Mounted Drives

If you mount a remote Novell Netware or Windows NT drive on your local NT system and assign a drive letter to it, the iPlanet web server always returns a "Not Found" error if you try to access any files from that drive through your web server. This happens even if you set up your document root or URL mappings to point to the remote drive.


Workaround

The iPlanet web servers on Windows NT don't directly support handling document directories on remote-mounted volumes, but this generally seems to work, as long as you are aware of some known issues with it.

UNC ("universal naming convention", such as \\servername\path\) paths are not supported. You must map a drive letter to the remote volume you want to use before your iPlanet web server can serve files from it. Here is how to set up a drive mapping for your iPlanet web server:

  1. Change the user that your iPlanet web server runs as from the system account (the default) to some other NT user on your system who has access to the network volume you want to use. Do this by opening the Services control panel in Windows NT, selecting the proper service for your web server (such as, https-servername for Web Server), clicking the Startup... button, then selecting the radio button by This Account and entering the username and password. Then close the dialog and the Services control panel.

  2. Log out of Windows NT, then log in as the user you previously specified.

  3. From a DOS window, run the following command:

    net use X: \\servername\path\directoryname /persistent:yes

    where X: is the drive letter you want to use (anything that's not currently in use), and \\servername\path\directoryname is the complete UNC path to the directory you want to mount as that drive letter. You can also set up this mapping from File Manager or Windows Explorer as long as you check the Reconnect at Login checkbox in the drive mapping dialog. You can log out from that user's account after you set this up.

Now, if you set up a drive mapping for X:, you should be able to tell your iPlanet web server to use its primary document directory on X:\, for example.

This may not work in all situations. If it doesn't, try upgrading to the latest copy of the client networking software for your computer. In particular, we have seen this fail if you're using the Microsoft networking software to connect to a Novell Netware file server; installing Novell Netware client software instead seems to fix the problem. Using drives mounted by Windows Networking and PC-NFS seems to work fine.

As noted above, using network volumes isn't directly supported by the iPlanet web server, and this may not work reliably.


Problem 338917. Cannot get environment variables configured for cmd scripts

The obj.conf file allows the configuration of environment variables for CGIs that run from the URL or via Parsed HTML. However, server-side includes for commands do not receive these environment variables.


Workaround

Add addCgiInitVars="yes" to your obj.conf file to get these variables subsequently passed to shtml-init. For example, if you add the following code to your obj.conf file:

Init fn="init-cgi" LateInit="yes" var1="xy" var2="ab"
Init fn="shtml_init" addCgiInitVars="yes"

Then any command executed from shtml via the use of the cmd directive will see var1="xy" and var2="ab" in its environment.


Problem 385142. Security Tab Cannot Be Delegated

You cannot delegate the Security tab. Only the primary administrator can change the security settings.


Problem 381644. Administration Server UI cannot handle variable font sizes

The Administration Server UI tabbed header hard-codes the font to be a particular size (roughly 12-18 points on various browsers). If the font is too small or too large, elements of the UI do not always expand or shrink in proportion. If the font is too large, the right arrow that displays the right most tabs may not be visible.


Problem 382458 (Unix only). Database Libraries Need to Be Set in LD_LIBRARY_PATH

On Linux, to connect to any database using iPlanet Web Server 4.1, you must point the LD_LIBRARY_PATH environment variable to the client library directory. For example (the following must be all on one line):

setenv LD_LIBRARY_PATH ${DB2PATH}/lib:${ORACLE_HOME}/lib:${INFORMIXDIR}/lib:
${INFORMIXDIR}/lib/esql:${SYBASE}/lib


Problem 387590 (Linux, Solaris and NT platforms only). Encryption Ciphers/Settings Reset to Default Values

Changes you make to the cipher settings (in the Encryption Preferences page of the Administration Server interface) are not saved when you select the OK button and then restart the server.


Workaround

Change the cipher settings by editing the magnus.conf file. For more information, see the Security section of the magnus.conf appendix in the NSAPI Programmer's Guide.


Problem 388625. Example Server Pages Still Use Netscape URL Links

Some sample pages installed in the docs directory still have URLs with references to Netscape and Netscape locations, such as home.netscape.com instead of iPlanet and iplanet.com/docs. Please use the following URL in place of the Netscape URL:

http://docs.iplanet.com/docs/manuals/enterprise.html


Problem 360250. Quality Feedback Agent (Talkback) Feature Not Operational

The required libraries from FullSoft, Inc. are not yet available. This feature will be re-enabled in a future Web Server release.


Problem 386805. Installer and Administration Server Do Not Recognize Errors in Base DN

Do not use illegal characters, such as colons (:), in the base DN when enabling LDAP. Web Server 4.1 Installer and the Administration Server do not check for illegal syntax or characters in the base DN.


Problem 384779. Advanced Search Applet Cuts Off Readable Text

The advanced search applet cuts off readable text if no collections are available. The actual message should be "No search collections available."


Problem 385149. Delegating Users & Groups Tab Causes Display Problems

All the information after "Users & Groups" in the upper frame is lost when you exit and re-enter the Restrict Access page without updating anything. However, information saved in the generated.https-admserv.acl file is not changed.


Problem 390064. Home Page Field in Document Preferences Page Cannot Recognize URL

The Home Page field in the Document Preferences page on the Content Mgmt tab of the Server Manager does not accept a URL. Instead, you must provide an absolute path or a relative path from the primary document directory.


Problem 394322 (HP-UX only). Poor SSL performance in single process mode

If there is a problem with poor SSL performance we recommend adding RqThrottleMinPerSocket 512 and MaxProcs X to the magnus.conf file, where X in the MaxProcs statement is greater than the number of CPUs in the system.


Problem 400714. Web Publisher Applet and SSL

The Web Publisher Java applet is not supported in SSL mode.


Problem 410728. Server shutdown appears to fail after creating IP addresses for multiple virtual servers

The first time the server is shut down after adding IP addresses for multiple virtual servers, the server may exceed the expected shutdown time. By default, an error message will appear, claiming server shutdown has failed. This message should be ignored as the server is actually in the process of shutting down. Subsequent shutdown attempts will not experience a prolonged shutdown time.


Problem 416848. MaxProcs + LDAP SSL + hardware accelerator does not work

Setting MaxProcs and LDAP SSL with a hardware accelerator enabled does not allow the hardware accelerator to work with child processes.


Problem. iPlanet Web Server SNMP Master Agent won't start on ports other than 161with the user interface.

Workaround

Though you cannot start the Master Agent through the user interface, you can start it by hand.

Edit /server_root/plugins/snmp/magt/CONFIG to specify the desired port.

Run the start script as follows:

cd /server_root/https-admserv

./start -shell /server_root/plugins/snmp/magt/magt

/server_root/plugins/snmp/magt/CONFIG

/server_root/plugins/snmp/magt/INIT

The master agent will then start on the desired port. However, the user interface will be able to detect that the master agent is running.

Java and Java Servlets


Servlet Error Information Not Available in iPlanet Web Server 4.1 Error Log

Due to the way the Servlets are "external" to the iPlanet Web Server, the output is not directed to the web server's error log. Instead, the output goes directly to standard output file of the web server process. Note that output from servlets goes to the STDERR of the process that started the web server if you use system.out.println() (or anything that uses the system.out object). In addition, note that the provided out object is in fact properly written to the server's error log.

So, for example, if you start the web server from a terminal window, you should see the output there. Use standard Unix file redirection to pipe the standard output into a file (that is, modify your server_root/https-instance/start file). You can use the ServletContext.log method to write to the error log file.


Multiple Headers and Servlets calling getHeaders

iPlanet Web Server 4.1 collapses multiple headers that came in on a request with the same name into a single header, with values comma separated. As a result of this, a servlet calling getHeaders always gets back an enumeration containing one string that has all the values separated by commas.


New Session ID generation

Session ID generator, which is used for Servlet sessions, employs cryptographically-strong unique random number generation algorithms. This may present a performance problem on older, slow machines. The Session Manager API (see the SimpleSessionManager.java example) allows you to redefine the random ID generation method and customize it to your particular needs.


Problem 387702. Content Length Set to 0 After a Servlet Sets It

If a servlet uses the HttpServletResponse.setContentLength method to convey the length of data that would be sent to the client but does not actually send the data over, the web server resets the content length to 0.


Problem 390226. Unable to Set the Expiration for a Session

Sessions are not getting invalidated when the setMaxInactiveInterval method is used.


Workaround

Set the session expiration in the servlets.properties configuration file. For example:

servlets.sessionmgr=com.netscape.server.http.session.YourSesMgr
servlets.sessionmgr.initArgs=maxSessions=20,timeOut=300,reapInterval=150


Problem 395924. Using regular expressions in rules.properties to redirect all URIs ending in an extension to a named servlet doesn't effectively work

Web Server supports regular expressions in the rules.properties file to run a given servlet when the incoming URL matches with a regular expression:

# Servlet rules properties (autogenerated)
# This file specifies the translation rules for invoking servlets.
# The syntax is:
#
# <virtual-path>=<servlet-name>
# or
# @regular_expression=<servlet-name> (use double back-slashes)
#
# Example:
#
# /simple=SimpleServlet\n
# @.*\\.foo=wasp

Where those "\\" characters are supposed to escape the "." extension. The intent is to run the example wasp servlet whenever there is a request for urls like /my/xxx.foo. Web Server 4.1 has a defect whereby it would replace the "/" characters or "\" characters with "/", subsequently changing the whole semantics.


Workaround

Specify the regular expression without those "/" or "\" characters:

@.*[.]foo$=wasp


Problem 398424 (Windows NT only). The sdk_test.bat/sdk_test.sh Examples May Fail to Compile

Compiling the examples on Windows NT platforms using sdk_test.bat may not work correctly. Follow the instructions in readme.html to compile the code manually using javac.


Problem 450189. Server not able to start when chrooted and servlets are active

With servlets active in the default configuration, the web server is not able to start once chrooted. Removing servlets allows the server to start and begin serving pages.


Problem 398234. The JVM does not take the system environment variables from the jvm.option settings

If you define JVM environment variables using the jvm.option setting in the jvm12.conf file or the Administration Server, servlets do not recognize them.


Workaround

When you are running a standalone command line java program, use the following option to pass system properties into the java program:

java -Dorg.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB myprogram

In the myprogram.java file, the following line retrieves the system property set above:

System.out.println("org.omg.CORBA.ORBClass="+System.getProperty("org.omg.CORBA.ORBClass"));

If you want to do the same thing for servlets in iPlanet Web Server, you need to put the following line in the jvm12.conf file:

org.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB

Do not use jvm.option settings such as the following:

jvm.option=-Dorg.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB

or

jvm.option=org.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB

In the servlet or JSP, you can use the following line to retrieve the system property set above:

out.println("org.omg.CORBA.ORBClass="+System.getProperty("org.omg.CORBA.ORBClass"));

NSAPI


Problem 531887. ACL doesn't work on CGI files

If you disable AcceptLanguage in the magnus.conf and enable the NSAPI cache in the obj.conf, an ACL protects CGI output only on the first request, but subsequent requests to the CGI are not protected.


Workaround

Do not use the NSAPI cache. This cache can interfere with the proper functioning of the ACL subsystem.


Problem 343875. URL Forwarding

A new PathCheck function called set-virtual-index specifies a virtual index for a directory, which determines the URL forwarding. The index can refer to a LiveWire application, a servlet in its own namespace, a Netscape Application Server applogic, and so on.

REQ_NOACTION is returned if none of the URIs listed in the from parameter match the current URI. REQ_ABORTED is returned if the file specified by the virtual-index parameter is missing or if the current URI cannot be found. REQ_RESTART is returned if the current URI matches any one of the URIs mentioned in the from parameter or if there is no from parameter.



Table 4    set-virtual-index Parameters

Parameter

Description

virtual-index 

The URI of the content generator that acts as an index for the URI the user enters. 

from 

An optional comma-separated list of URIs for which this virtual-index is applicable. If from is not specified, the virtual-index always applies.  


Problem 385457 (Windows NT). Multi-Process Mode Not Supported

On Windows NT, multi-process mode is not supported. This means that the MaxProcs directive in the magnus.conf file can not have a value greater that 1. For more information, see the magnus.conf appendix in the NSAPI Programmer's Guide.


Problem 524191. Multi-Threaded NSAPI SAFs Crash

Workaround: When writing multi-threaded NSAPI SAFs for iPlanet Web Server 4.1 and greater, you must call the function prepare_nsapi_thread(rq, sn). This should be the first call of any new thread. This replaces the need to do systhread_setdata(getThreadMallocKey(), sn->pool), which was used in earlier server versions.

The function may need to be forward declared when compiling with early service packs of 4.1. The declaration should look like this:

NSAPI_PUBLIC void prepare_nsapi_thread (Request * rq, Session * sn);

Security


Problem 526797 Admin Server cannot connect to secure ldap server with Use SSL selected if Admin Server (or https instance) is not SSL enabled

The listener processes must be able to establish a trust relationship with the LDAP server they must be able to open their Certificate Databases to examine the trust chain of the received LDAP certificate. If the instance (Admin Server or individual instances) is not SSL enabled then it is unable to open the certificate database and appears "hung" while attempting to open the database.


Workaround

Provide password.conf as documented at:

http://docs/docs/manuals/enterprise/41/ag/essvrprf.htm#1012001

("Restarting an SSL Server"). Sample format is:

Communicator Certificate DB: password!

This must be provided for each instance that needs to communicate with the SSL enabled LDAP server.


Problem 383530 (Windows NT only). Encryption Error

The following error message may appear when you turn Encryption on with the default settings (in the Encryption On/Off page on the Preferences tab of either the Administration Server or the Server Manager), select Save and Apply, and enter your password:

Commit.exe Application error
the instruction at "0x780001146" referenced memory at "0x00661006d".
The memory could not be "written".
Click OK to terminate the application.

Select OK, and the following message appears:

Success! Your changes have been saved.

After you see this message, you should verify that the server has been restarted by going to the Shut Down or Server On/Off page on the Preferences tab or to the Services Control Panel.


Problem 389276 (Solaris). Adding Server Certificates to Hardware Tokens Causes Server to Prompt for Internal Certificate DB Password

If you create a new server instance with SSL and store your certificate on a hardware token, you may be prompted to enter both the nCipher password and the internal software password when you start up the server instance. No matter which password you enter, the server does not start. The error log shows the following lines:

test-kra# ./start
test-kra# [22/Mar/2000:15:26:03] info ( 2614): successful server startup
[22/Mar/2000:15:26:03] info ( 2614): iPlanet-WebServer-Enterprise/4.1 BB1-03/06/2000 00:55
[22/Mar/2000:15:26:03] failure ( 2614): NSS initialization failed: -8174


Workaround

Follow these guidelines to avoid this problem:


Problem 389288. CSRs with Regular Expressions are rejected

If you try to request a certificate with a regular expression in it, such as (test|production).acme.com, your certificate may be rejected by the CA. Many CAs will not issue certificates that contain regular expressions.


Problem 386677 (Linux, Solaris and Windows NT only). Typo in Pop-Up When Turning on Server Encryption

When you install a new server certificate and enable encryption via the Administration Server "enable encryption: yes" settings, the Web Server displays the following information:

Warning: Security changes require shutdown
In order for your changes to take effect, you will need to shutdown the
HTTP server, and then start it up again from the console in order to enter
the keyfile password. After you have started up the server again, your
server's url will be http://nocturne.netscape.com:9000 instead of
http://nocturne.netscape.com:9000


Problem 387226. Session Cache Problem with Client Authentication

Note the following information regarding the magnus.conf file SSLCacheEntries directive:


Problem 396337 (Windows NT only). Configuration Change Windows Do Not Check for Correct Password (when SSL is Enabled)

If SSL is enabled on the server and you change any configuration on Windows NT platforms, and then click Save and Apply, the Web Server displays the "System error: Password did not match" error message.


Workaround

Click the Save and then click the Apply button at the right top of the Administration Server.


Problem. Microsoft Internet Explorer 4.x and 5.0 Unable to Perform 128-bit Step-Up

The export releases of Internet Explorer 4.x and 5.0 do not properly request a cipher change from 40/56-bit to 128-bit encryption when they encounter a step-up certificate. Internet Explorer does not perform the step-up and continues communicating with iPlanet Web Server using a 40/56-bit cipher. This issue has been reported to Microsoft.


Workaround

Microsoft recommends upgrading to a 128-bit capable browser.

Server-Side JavaScript (SSJS) / LiveWire


Problem 382457 (Linux only). Web Server Crashes When Sybase Connection Fails

On Linux, if you connect to a Sybase server using LiveWire and the connection fails, the web server crashes. The server crashes because the LANG and LC_ALL environment variable values do not match values in the locales.dat file.

Workaround: Modify the ${SYBASE}/locales/locales.dat file so that it has an entry for the locale that you want. For example, if you set LANG=en_US or LC_ALL=en_US or both, add the following entry to the [linux] section in locales.dat:

locale = en_US, us_english, iso_1


Problem 385237 (Linux only). Unstable Databases

LiveWire may exhibit problems on Linux platforms with all databases (except Informix) when running under stress conditions.


Problem 394712. Users can't access CGI variables from within a servlet

You can not access the internal getCgiVariable() functionality from the servlet HttpServletRequest interface. If you try, the server displays the following compilation error:

WASPServlet.java:269: Method getCgiVariable(java.lang.String) not found in
interface javax.servlet.http.HttpServletRequest.
String cgiVar = req.getCgiVariable("PATH_TRANSLATED");
^
Note: WASPServlet.java uses or overrides a deprecated API. Recompile with
"-deprecation" for details.
1 error, 1 warning




Platform-Specific Information

This section describes platform-specific known problems and workarounds for the following platforms:

Linux Platforms


Web Publisher and Search

iPlanet Web Server, Enterprise Edition 4.1, does not support the Web Publisher or Search features on Linux platforms.


Support for Multithreaded Database Applications on Linux

Oracle Client SDK version 8.0.5 and DB2 Client SDK version 6.1 support multithreaded database applications.


Problem 382457. Web Server Crashes When Sybase Connection Fails

On Linux, if you connect to a Sybase server using LiveWire and the connection fails, the web server crashes. The server crashes because the LANG and LC_ALL environment variable values do not match values in the locales.dat file.


Workaround

Modify the ${SYBASE}/locales/locales.dat file so that it has an entry for the locale that you want. For example, if you set LANG=en_US or LC_ALL=en_US or both, add the following entry to the [linux] section in locales.dat:

locale = en_US, us_english, iso_1


Problem 382458. Database Libraries Need to Be Set in LD_LIBRARY_PATH

On Linux, to connect to any database using iPlanet Web Server 4.1, you must point the LD_LIBRARY_PATH environment variable to the client library directory. For example (the following must be all on one line):

setenv LD_LIBRARY_PATH ${DB2PATH}/lib:${ORACLE_HOME}/lib:${INFORMIXDIR}
/lib:${INFORMIXDIR}/lib/esql:${SYBASE}/lib


Problem 385237. Unstable Databases

LiveWire may exhibit problems on Linux platforms with all databases (except Informix) when running under stress conditions.


Problem 391820. Perl scripts fail with .pl extensions

Perl scripts fail with .pl extensions when the .pl extension has a specific mime.type x application.


Workaround

The problem can be resolved by commenting out the x application mime.type extension for .pl.

Solaris Platforms


Problem. Potential server instability.

If you use Solaris 7 you may see instability within the server if you are not using the correct patch cluster.


Workaround

Install Solaris patch cluster 106541-12.

HP-UX Platforms


Problem 392921 (HP-UX only). Cannot Have Only SSL2 Enabled on the Administration Server

If you enable only SSL2 on the Administration server, then stop and start the Administration Server, you can no longer access it. The server seems to come up fine and leaves no errors in the error log, but it is not accessible.


Workaround

Enable SSL3 as well.


Problem 394322 (HP-UX only). Poor SSL performance in single process mode

If there is a problem with poor SSL performance we recommend adding RqThrottleMinPerSocket 512 and MaxProcs X to the magnus.conf file, where X in the MaxProcs statement is greater than the number of CPUs in the system.

IBM AIX Platforms


Java Support

If you are using a JDK, download version 1.2.2, update ca122-20000726 or later from http://www.ibm.com/java/jdk/aix/index.html. Java support should work fine as installed. However, if your server hangs when processing servlets and JSPs, check that the following line is set properly:

jvm.serializeFirstRequest=1

in server_root/https-admserv/config/jvm12.conf.

Windows NT Platforms


Problem 44812 (Windows NT only). Windows NT iPlanet Web Server Cannot Find Files on Remote-Mounted Drives

If you mount a remote Novell Netware or Windows NT drive on your local NT system and assign a drive letter to it, the iPlanet web server always returns a "Not Found" error if you try to access any files from that drive through your web server. This happens even if you set up your document root or URL mappings to point to the remote drive.


Workaround

See the workaround under General Known Problems and Solutions.


Problem 385457. Multi-Process Mode Not Supported

On Windows NT, multi-process mode is not supported. This means that the MaxProcs directive in the magnus.conf file cannot have a value greater than 1. For more information, see the magnus.conf appendix in the NSAPI Programmer's Guide.




Internationalization Information

This section includes information regarding internationalization issues.

Note that the English version of iWS4.1sp7 can be safely installed over an existing Internationalized/Localized build of an earlier version of iWS.


Problem 381384, 396154. Internationalization in Parameters

Sometimes problems occur when a user includes non-ASCII characters in a parameter passed to a servlet.


Workaround

Set the context.global.parameterEncoding property in the contexts.properties file properly. If a servlet uses the ServletRequest.getParameter method, set parameterEncoding to auto and follow the instructions below.

The context.global.parameterEncoding property allows you determine the character encoding of servlet parameters. It has the following options:



Table 5    parameterEncoding Options

Option

Description

any supported Java character encoding 

Any supported encoding, as listed at http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html 

none 

Uses the system default encoding. Set this option if the encoding of the servlet parameter data is the same as the system default encoding.  

responseCT 

Use this option if you wish the response content-type (set using response.setContentType()) to be used for the servlet parameter data. 

auto 

(Default) Tries to figure out the proper encoding from the charset if it is set in the Content-Type header. Otherwise, the system default encoding is used. Set this option to prevent misinterpretation of non-ASCII characters in servlet parameters.

When this property is set to auto, the server has to convert native characters into a java byte array before transforming them into the requested encoding. Therefore, performance is slightly better for a supported java character encoding or none.

If this option is specified, the servlet container looks for some hints for the character encoding to be used. The hint can be specified in two ways:

  1. As a request attribute. The servlet developer can set the request attribute using the name: "com.iplanet.server.http.servlet.parameterEncoding"

    The value is of type String. Note that the request attribute needs to be set before any calls to getParameter() or getParameterValues(). Example:

    request.setAttribute("com.iplanet.server.http.servlet.parameterEncoding"

    "Shift_JIS");

request.getParameter("test");

This option is used if the servlet that is reading the data knows beforehand what the charset of the posted data is.

  1. As a j_encoding parameter in the form data . The form that is being submitted can have a hidden element :

<input type=hidden name="j_encoding" value="Shift_JIS" >

This option is typically used if the sevlet that is reading the data does not necessarily know what the charset of the posted data is.

 

If a servlet uses the ServletRequest.getParameter method to retrieve values in form fields having something other than a supported Java character encoding, the parameterEncoding property must be set to auto (the default) in the contexts.properties file. Otherwise, the values extracted by the getParameter method are zeros or are undefined.

Because the original encoding used to enter data into form fields is lost when the data is URL-encoded, you must do the following:




ValiCert Web Server Validator 2.5 for iPlanet Web Server, Enterprise Edition

The ValiCert Web Server Validator is an NSAPI plug-in that adds automatic certificate validation, including CRL checking, to the iPlanet Web Server, Enterprise Edition. The product plugs into the iPlanet Web Server, Enterprise Edition, enabling you to check the revocation status of digital certificates issued by all major CAs. This added capability helps to protect you against exposure to liability and fraud that can occur if a user's certificate is lost or stolen. Specific benefits of the ValiCert Web Server Validator for iPlanet Web Server, Enterprise Edition include the following:

The ValiCert Web Server Validator is available for download from the iPlanet Web Server, Enterprise Edition 4.1 CD-ROM, under the directory labeled /valicert. For additional information about the Web Server Validator, and to download the latest version, please go to http://www.valicert.net/netscape.

If you have any questions, please contact ValiCert technical support at support@valicert.com.




Using the Load Balancing Plug-in: libresonate

Overview

This plug-in is allows the server to execute a program when certain thread load conditions are met so a load distribution product on the front-end can redistribute the load.

There are two methods that you can use to trigger the load balancer to increase or decrease load:

Standard: Base load decisions on the number of queued requests. This is a passive approach. By letting the queue fill up you are already delaying some requests. In this case you want the HighThreshold to be a low value and LowThreshold to be a high value.

Aggressive: Base load decisions on the number of active threads in the pool. This is designed to more tightly control the requests so that you would reduce the load before requests get queued.

Thread pool configuration

For Unix platforms, you need to set up a specific thread pool for the plug-in to monitor. You can do this from the Admin screen by selecting your instance and choosing Thread Pools.

Create a new thread pool with the settings that you want, the Administrator's Guide has a good description of how to do this and what each setting means. You are probably okay with just setting the minimum and maximum threads.

Configuring thread pools will add something like the following example into your server_root/https-instance/config/obj.conf file:

Init name="sleep" MinThreads="1" MaxThreads="10" EarlyInit="yes" fn="thread-pool-init"

Library configuration

In order to enable the plug-in, you need to modify obj.conf manually. This should look something like this:

Init fn="load-modules" funcs="init-resonate" shlib="server_root/bin/https/lib/libresonate.so"

Init fn="init-resonate" ThreadPool="sleep" EventExePath="/tools/ns/bin/perl5" LateInit="yes" CmdLow="/usr/netscape/ent41/plugins/loadbal/CmdLow.pl" CmdHigh="/usr/netscape/ent41/plugins/loadbal/CmdHigh.pl"

The init-resonate function can take the following parameters:



Table 6    init-resonate Parameters

Parameter

Description

ThreadPool 

the name of the thread pool to monitor  

Aggressive 

if set to TRUE this argument causes the plug-in use the pool thread count rather than the queue thread count  

PollTime 

how frequently to check the thread status, by default 2000 seconds 

HighThreshold 

defines the queue size/# of threads where HighCmd is executed in order to increase load on the server. The default is 4096.  

LowThreshold 

defines the queue size/# of threads where the LowCmd is executed in order to decrease load on the server. The default is 1. 

EventExePath 

pointer to the script program you want to run (i.e. /usr/bin/perl or /bin/sh). Defaults to perl or perl.exe depending on platform. 

CmdLow 

pointer to the script to be run when the LowThreshold is met 

ArgsLow 

arguments to send to CmdLow  

CmdHigh 

pointer to the script to be run when the HighThreshold is met  

ArgsHigh 

arguments to send to CmdHigh  



Note

You must specify LateInit="yes" when loading this module. This is because the module creates a monitoring thread and this monitoring thread needs to start after ns-httpd has started.



Setting LogVerbose on in magnus.conf will cause the server to print a lot of information to the error log on how the plug-in is configured and when it is invoked.

A sample of this is shown below:

[12/Jun/2000:09:36:35] verbose (20685): Resonate plugin watching thread pool sleep
[12/Jun/2000:09:36:35] verbose (20685): Resonate plugin aggressive setting is FALSE
[12/Jun/2000:09:36:35] verbose (20685): Resonate plugin poll time set to 2000
[12/Jun/2000:09:36:35] verbose (20685): Resonate plugin HighThreshold set to 5
[12/Jun/2000:09:36:35] verbose (20685): Resonate plugin LowThreshold set to 1
[12/Jun/2000:09:36:35] verbose (20685): Resonate plugin event executable path set to /tools/ns/bin/perl5
[12/Jun/2000:09:36:35] verbose (20685): Resonate plugin low command set to /usr/netscape/ent41/plugins/loadbal/CmdLow.pl
[12/Jun/2000:09:36:35] verbose (20685): Resonate plugin high command set to /usr/netscape/ent41/plugins/loadbal/CmdHigh.pl

This is what will the log entries will look like when LogVerbose on is set and the plugin is activated:

[12/Jun/2000:09:40:12] verbose (20699): Resonate plugin reducing load.
[12/Jun/2000:09:40:14] verbose (20699): Resonate plugin reducing load.
[12/Jun/2000:09:40:16] verbose (20699): Resonate plugin reducing load.
[12/Jun/2000:09:40:18] verbose (20699): Resonate plugin reducing load.
[12/Jun/2000:09:40:20] verbose (20699): Resonate plugin reducing load.
[12/Jun/2000:09:40:30] verbose (20699): Resonate plugin increasing load.

Testing

A simple way to test the load balancer is to use an NSAPI that prints a little HTML page and then calls sleep() for a period to simulate execution time. This way one can build up a simulated load on the server and ensure that the load balancer commands are working properly.

To configure the sample program, first we want to add a new MIME type so this isn't run for every request. Modify config/mime.types and add a line like this:

type=magnus-internal/sleep exts=sleep

Then create a file in your document-root directory with the extension of .sleep. It doesn't matter if anything is in this file, it is used as a placeholder only.

To load the module into the server, add a line like this to your obj.conf, changing shlib to the location of the library. You also have to set pool to the name of the thread pool you defined earlier:

Init fn="load-modules" funcs="dosleep" shlib="/usr/netscape/ent41/plugins/nsapi/examples/dosleep.so" pool="sleep"

Then add this Service line where the others are found (note that order is not important):

Service method="(GET|HEAD)" fn="dosleep" duration="10" type="magnus-internal/sleep"

The argument duration tells the server how long to sleep for each request in seconds.

Now start your server and you should be ready to go to test the load balancer plug-in. The NSAPI will keep the threads busy long enough to similar whatever load you want. The plug-in is tested by retrieving the .sleep file you created earlier.

Sample Configuration

Nothing special needs to be done in magnus.conf. The only setting that will affect the plug-in is LogVerbose on. Below is a sample obj.conf.

# Sun Netscape Alliance - obj.conf
# You can edit this file, but comments and formatting changes
# might be lost when the admin server makes changes.

Init fn="flex-init" access="/usr/netscape/ent41/https-resonate/logs/access" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"
Init fn="load-types" mime-types="mime.types"
Init fn="load-modules" funcs="init-resonate" shlib="/usr/netscape/ent41/bin/https/lib/libresonate.so"
Init name="sleep" MinThreads="1" MaxThreads="10" EarlyInit="yes" fn="thread-pool-init"
Init fn="init-resonate" ThreadPool="sleep" EventExePath="/tools/ns/bin/perl5" LateInit="yes" CmdLow="/usr/netscape/ent41/plugins/loadbal/CmdLow.pl" CmdHigh="/usr/netscape/ent41/plugins/loadbal/CmdHigh.pl" HighThreshold="2" LowThreshold="5"
Init fn="load-modules" funcs="dosleep" shlib="/usr/netscape/ent41/plugins/nsapi/examples/dosleep.so" pool="sleep"
Init fn="load-modules" shlib="/usr/netscape/ent41/bin/https/lib/libNSServletPlugin.so" funcs="NSServletEarlyInit,NSServletLateInit,NSServletNameTrans,NSServletService" shlib_flags="(global|now)"
Init fn="NSServletEarlyInit" EarlyInit="yes"
Init fn="NSServletLateInit" LateInit="yes"

<Object name="default">
NameTrans fn="NSServletNameTrans" name="servlet"
NameTrans fn="pfx2dir" from="/servlet" dir="/usr/netscape/ent41/docs/servlet" name="ServletByExt"
NameTrans fn="pfx2dir" from="/ns-icons" dir="/usr/netscape/ent41/ns-icons" name="es-internal"
NameTrans fn="pfx2dir" from="/mc-icons" dir="/usr/netscape/ent41/ns-icons" name="es-internal"
NameTrans fn="pfx2dir" from="/help" dir="/usr/netscape/ent41/manual/https/ug" name="es-internal"
NameTrans fn="pfx2dir" from="/manual" dir="/usr/netscape/ent41/manual/https" name="es-internal"
NameTrans fn="document-root" root="/usr/netscape/ent41/docs"
PathCheck fn="unix-uri-clean"
PathCheck fn="check-acl" acl="default"
PathCheck fn="find-pathinfo"
PathCheck fn="find-index" index-names="index.html,home.html"
ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"
Service method="(GET|HEAD)" fn="dosleep" duration="10" type="magnus-internal/sleep"
Service method="(GET|HEAD)" type="magnus-internal/imagemap" fn="imagemap"
Service method="(GET|HEAD)" type="magnus-internal/directory" fn="index-common"
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
AddLog fn="flex-log" name="access"
</Object>

<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>

<Object name="servlet">
ObjectType fn="force-type" type="text/html"
Service fn="NSServletService"
</Object>

<Object name="jsp092">
ObjectType fn="type-by-extension"
ObjectType fn="change-type" type="magnus-internal/jsp092" if-type="magnus-internal/jsp"
Service fn="NSServletService" type="magnus-internal/jsp092"
</Object>

<Object name="ServletByExt">
ObjectType fn="force-type" type="magnus-internal/servlet"
Service type="magnus-internal/servlet" fn="NSServletService"
</Object>

<Object name="es-internal">
PathCheck fn="check-acl" acl="es-internal"
</Object>

<Object ppath="/usr/netscape/ent41/docs/.perf" 2=">">
Service fn="service-dump"
</Object>

Below is a sample dosleep.c:

#ifdef XP_WIN32
#define NSAPI_PUBLIC __declspec(dllexport)
#else /* !XP_WIN32 */
#define NSAPI_PUBLIC
#endif /* !XP_WIN32 */

#include "nsapi.h"

#define BUFFER_SIZE 1024

#ifdef __cplusplus
extern "C"
#endif
NSAPI_PUBLIC int dosleep(pblock *pb, Session *sn, Request *rq)
{
char buf[BUFFER_SIZE];
int length, duration;
char *dur = pblock_findval("duration", pb);

if (!dur) {
log_error(LOG_WARN, "dosleep", sn, rq, "Value for duration is not set.");

return REQ_ABORTED;
}

duration = atoi(dur);

/* We need to get rid of the internal content type. */
param_free(pblock_remove("content-type", rq->srvhdrs));
pblock_nvinsert("content-type", "text/html", rq->srvhdrs);

protocol_status(sn, rq, PROTOCOL_OK, NULL);

/* get ready to send page */
protocol_start_response(sn, rq);

/* fill the buffer with our message */
length = util_snprintf(buf, BUFFER_SIZE, "<title>%s</title><h1>%s</h1>\n", "Sleeping", "Sleeping");
length += util_snprintf(&buf[length], BUFFER_SIZE - length, "Sample NSAPI that is sleeping for %d seconds...\n", duration);

/* write the message to the client */
if (net_write(sn->csd, buf, length) == IO_ERROR)
{
return REQ_EXIT;
}
sleep(duration);
return REQ_PROCEED;
}




LiveWire Database Client Versions

The following sections lists the database vendor client libraries supported on Linux and Solaris 8 by iPlanet Web Server, Enterprise Edition 4.1.

Linux

The following table lists the database vendor client libraries supported on Linux by iPlanet Web Server, Enterprise Edition 4.1:



Table 7    Database Vendor Client Libraries Supported on Linux

Database

Library Supported

Oracle 

8.0.5 

Informix 

2.30.UC11 

Sybase 

11.1.1 

DB2 

6.1 

Note that LiveWire may exhibit problems on Linux platforms with all databases (except Informix) when running under stress conditions.


Support for Multithreaded Database Applications on Linux

Oracle Client SDK version 8.0.5 and DB2 Client SDK version 6.1 support multithreaded database applications.

Solaris 8

The following table lists the database vendor client libraries supported on Solaris 8 by iPlanet Web Server, Enterprise Edition 4.1:



Table 8    Database Vendor Client Libraries Supported on Solaris 8

Database

Library Supported

Oracle 

8.0.5 

Note that this is a Solaris 8 limitation since the ISVs are committed to certifying their databases at a later date.




Corrections to Documentation

Please note the following changes to the iPlanet Web Server, Enterprise Edition 4.1 documentation.


Problem 543893. Administration Guide Gives Wrong Configuration for Multiple HW Virtual Servers

The documentation in the Administration Guide for iWs 4.1 incorrectly states that you can configure multiple hardware virtual servers on the same IP address by assigning a unique port number for each hardware virtual server through the user interface. The port option cannot be specified via the user interface, but is a valid option. The user interface correctly creates the address= option.

The correct syntax to assign a unique port number for each hardware virtual server using the same IP address is:

NameTrans fn="document-root" address="123.45.6.7" root="/tmp" port="90"

Also, The NSAPI Programmer's Guide does not completely document address= or port= for the NameTrans directive.


Problem 534978. MMapSessionManager Incorrect in Programmer's Guide to Servlets (Appendix A)

The documentation in the Programmer's Guide to Servlets for iWs 4.1 incorrectly states that MMapSessionManager can be used for sharing session information across multiple processes possibly running on different machines. MMapSessionManager should not be used across different machines.

Problem 540048. Incorrect Separator for JRE/JDK Path

The Administrator's Guide states that the path in "start-jvm" file should be separated with semicolons, which is true for NT; but the path should be separated by colons for Unix.




Problem 545084. Default Mode for Init Is Not LateInit.

The NSAPI Programmer's Guide incorrectly states that the default mode for Init is LateInit=yes. The default behavior is EarlyInit.


Problem with UseOutputStreamSize in NSAPI Programmer's Guide (Appendix B & G)

The NSAPI Programmer's Guide describes UseOutputStreamSize as a magnus.conf directive. UseOutputStreamSize is recognized in both magnus.conf and obj.conf. However, UseOutputStreamSize=0 only has meaning in obj.conf.

The functions that do not work in the magnus.conf, but do work in obj.conf are:

flushTimer

ChunkedRequestTimeout

ChunkedRequestBufferSize


Problem 533898. NSAPI Programmer's Guide has problems with syntax

The NSAPI Programmer's Guide has incorrect syntax in the Logging Options section. Under flex-rotate-init, the manual describes a parameter of rotate-interval, but the example shows rotate-intervals. If you use the plural string, the server will not start and complains it cannot init that line as it does not see rotate-interval & rotate-start.

To correct this problem, change the syntax to rotate-interval, and the server starts and the access log is rotated.


Problem 307321. NSAPI Specification Verification

In Table 4.1 of Chapter 4, "Creating Custom SAFs," in the NSAPI Programmer's Guide, the NSAPI functions that retrieve the CONTENT_LENGTH and CONTENT_TYPE CGI variables should be as follows:



Table 9    CGI Variable Corrections

CGI getenv()

NSAPI

CONTENT_LENGTH 

pblock_findval("content-length", rq->headers);  

CONTENT_TYPE 

pblock_findval("content-type", rq->headers);  


New password.conf Configuration File Information

Chapter 7, "Configuring Server Preferences," in the iPlanet Web Server Administrator's Guide has been updated to include the new password.conf configuration file. See the online version in the product, or see Starting and Stopping the Server.


Error in nostat Description

In "Miscellaneous obj.conf Parameters" in Chapter 10, "Configuring the Server for Performance," in the iPlanet Web Server Administrator's Guide, the section that describes the nostat parameter should read as follows:

For example:

<Object name=default>
...
NameTrans fn="assign-name" from="/nsfc" nostat="/nsfc" name="nsfc"
...
</Object>
<Object name="nsfc">
Service fn=service-nsfc-dump
</Object>


Problem 391661. Default Value for Size of DNS Cache Is Incorrect

The on-line help states that the default value for the size of the DNS cache is 1024 entries. However, when you enable the DNS cache from the Performance Tuning page under the Preferences tab, you see 512 displayed in the Size of DNS Cache field.


Error in RqThrottle Description

In the Performance, Tuning, Sizing, and Scaling Guide and in the "Tuning Your Server for Performance" section of the Administrator's Guide, in the section called "About RqThrottle," it says that you can set the timeout period in obj.conf. That is not correct. Use the AcceptTimout parameter in magnus.conf to adjust this period.


Error in perfdump Description

In the Performance, Tuning, Sizing, and Scaling Guide and in the "Tuning Your Server for Performance" section of the Administrator's Guide, the instructions for enabling perfdump are incorrect. They say to add the following object to your obj.conf file after the default object:

<Object ppath="/usr/netscape/server4/docs/.perf">
Service fn = "service-dump"
</Object>

However, the line Service fn = "service-dump" is incorrect. There shouldn't be any spaces around the equals sign. The correct example is:

<Object ppath="/usr/netscape/server4/docs/.perf">
Service fn="service-dump"
</Object>


Obsolete Security Directives in magnus.conf

In Appendix B of the NSAPI Programmer's Guide, the ServerCert and ServerKey directives are listed, but they are obsolete in iPlanet Web Server 4.x.


Undocumented Security Directive in magnus.conf: CERTDefaultNickname

Appendix B of the NSAPI Programmer's Guide, omitted the CERTDefaultNickname directive. Here is the description:

The CERTDefaultNickname directive is the nickname of the server certificate in the certificate database.

Syntax

CERTDefaultNickname name

The name is the nickname of the server certificate in the certificate database.

Default

There is no default. You must specify a name.


Problem 465149. Error in Server Restart Description

In the "Configuring Server Preferences" chapter of the Administrator's Guide, in the section called "Restarting the Server Manually (Unix/Linux)," it says that you can use the -p option. This option is no longer valid.

In addition, you must use the -start option, and it must be the first option. The syntax should read as follows:

server_root/https-server_id/start -start [-option1 -option2 ... ]

In the manuals, the server instance directory is sometimes called https-server_id and sometimes called type-identifier. Both of these mean the same thing.


Problem 523053. Hardware Virtual Server Example Clarification

In the "Administering iPlanet Web Servers" chapter of the Administrator's Guide, an example is shown in the section called "Configuring Multiple Hardware Virtual Servers on the Same IP Address with Different Ports." For the example to work, you must include the full path to the document root of each virtual server in the dir parameter.


Problem 526592. Access Control API Changes

Access control API changes for iPlanet Web Server 4.x are summarized in the file server_root/plugins/nsacl/api-notes.html.


Problem 400510. Buffered Streams Parameters

In the NSAPI Programmer's Guide, flushTimer was incorrectly documented as a magnus.conf directive; it is an obj.conf parameter common to all Service SAFs, like the type, method, and query parameters. UseOutputStreamSize, ChunkedRequestBufferSize, and ChunkedRequestTimeout are both magnus.conf directives and obj.conf parameters common to all Service SAFs. The example at the end of Appendix G is correct.


Incorrect Parameter Name

In the NSAPI Programmer's Guide, one of the parameters of the deny-existence SAF is listed as bong-msg. This should be bong-file instead.




How to Report Problems

If you have problems with iPlanet Web Server, contact iPlanet customer support using one of the following mechanisms:

So that we can best assist you in resolving problems, please have the following information available when you contact support:




For More Information

Useful iPlanet information can be found at the following Internet locations:

For iPlanet Web Server, Enterprise Edition 4.1 installation instructions, see the Installation and Migration Guide.

For iPlanet Web Server, Enterprise Edition 4.1 administrator documentation, see the online help that accompanies the product. The Administrator's Guide and related documents are also posted at: http://developer.iplanet.com/docs/manuals/enterprise.html.

If you can't find the information you need, please contact: ihttp://iplanet.com/support/support_services_10_0.html.

Last Updated March 21, 2002