Chapter 11 Extending Your Server With Programs

This chapter discusses how to install programs on the iPlanet Web Server that dynamically generate HTML pages in response to requests from clients. These programs are known as server-side applications. (Client-side applications, which are downloaded to the client, run on the client machine.)

• Overview of Server-Side Programs
• Java Servlets and JavaServer Pages (JSP)
• Installing CGI Programs
• Installing Windows NT CGI Programs
• Installing Shell CGI Programs for Windows NT
• Using the Query Handler
• Server-Side JavaScript Programs
• Enabling WAI Services

• Java servlets are written in Java, which is a full-featured programing language for creating network applications.
• CGI (Common Gateway Interface) programs can be written in C, Perl, or other programming languages. All CGI programs have a standard way of passing information between clients and servers.

Note that you must enable cookies in your browser to run CGI programs.

• JavaScript applications are written in JavaScript, an object-based scripting language. JavaScript is easier to learn than languages such as Java and C and it lends itself to rapid application development.

Types of Server-Side Applications That Run on the Server
The iPlanet Web Server can run the following types of server-side applications to dynamically generate content:

• Java servlets

• CGI programs


• JavaScript applications

• For Java servlets, you can configure your server to recognize all files in certain directories as servlets, or you can set up virtual pathnames for servlets, or both. For more information, see "What the Server Needs to Run Servlets and JSPs."
• For CGI programs, you can configure your server to recognize all files with certain filename extensions, or all files in specified directories as CGI programs, or both. For more information, see "Installing CGI Programs," "Installing Windows NT CGI Programs," and "Installing Shell CGI Programs for Windows NT."
• For JavaScript applications, you must check in each application individually through the Application Manager, which you can access from iPlanet Web Server. For more information, see "Installing Server-Side JavaScript Applications."

• Overview of Servlets and JavaServer Pages
• What the Server Needs to Run Servlets and JSPs


• Enabling Servlets and JSP


• Making JSPs Available to Clients


• Making Servlets Available to Clients


• Specifying Servlet Directories


• Configuring Global Attributes


• Configuring Servlet Attributes


• Configuring Servlet Virtual Path Translations


• Configuring JRE/JDK Paths


• Configuring JVM Attributes


• Deleting Version Files

http://www.javasoft.com/products/servlet/2.2/javadoc/ index.html

http://www.javasoft.com/products/jsp/index.html

http://www.javasoft.com/products/jdk/1.2/

• You can specify the path during the server installation process.

When you install iPlanet Web Server, one of the dialog boxes in the installation process asks if you want to use a custom Java Development Kit (JDK), and if so, you can specify the path to it.

• You can specify it after the server is installed.

To specify the path to the JDK, switch to the Web Server Administration Server, select the Global Settings tab, and use the Configure JRE/JDK Paths page. You can also change the path to the JDK in this page.

• iPlanet Web Server has been instructed to use the JDK.
• Both servlets and JSP are enabled in the server.

• Put the servlet class file in a directory that has been registered with iPlanet Web Server as a servlet directory. For more information, see "Specifying Servlet Directories."
• Define a servlet virtual path translation for the servlet. In this case, the servlet class can be located anywhere in the file system or even reside on a remote machine. For more information, see "Configuring Servlet Virtual Path Translations."

http://your_server/servlet/SimpleServlet

URL Prefix. The prefix for accessing the directory. For example, if you want the logical URL http://servername/plans to translate to the directory d:/netscape/server4/docs/plans then enter plans in the URL Prefix field.

Servlet Directory. The absolute pathname to the directory to be registered as a servlet directory, for example, d:/netscape/server4/docs/plans. iPlanet Web Server treats all files in the directory as servlets.

NameTrans fn="redirect" from="/foobar" url- prefix="index.html" escape="no"

• Servlets to run when the server starts up.
• The Session Manager to be used by servlets.
• The Session Manager Args (arguments) to be used by servlets.
• The amount of time the server waits before reloading servlets if they have changed.

Startup Servlets.. In this field, enter the name of servlets to be loaded when the web server starts up. You do not need to include the .class extension.

Session Manager.. If you have a session manager class, enter its value here.

Session Manager Args.. If you want to specify session manager arguments, enter the values here. Separate multiple name=value parameters with a comma. Input must be in the format name=value,name2=value2, and so on. For more information, see Appendix A, "Session Managers," in Programmer's Guide to Servlets for iPlanet Web Server.

Reload Interval.. This is the interval in seconds the server waits before reloading servlets and JavaServer Pages if they have changed. Specify an integer value here between 0 and 600 inclusive. The default value is 5 seconds.

In this page, you can specify the following fields:

Choose Servlet. Specifies the servlet to edit. If no virtual paths have previously been set up, the list is empty. Upon choosing the servlet from this drop-down list, the servlet's information is displayed in the page. (Ignore this field if you are adding a new virtual path entry).

Servlet Name. Specifies an identifier for the servlet. This identifier is used internally by iPlanet Web Server; it is not used in the URL for accessing the servlet. This identifier can be the same name or a different name than the servlet class name.

Servlet Code (class name). Specifies the name of the servlet's main class file. The .class extension is optional. Do not specify any directories in this field.

Servlet Classpath. This is the absolute pathname or URL to the directory or zip/jar file containing the servlet. The classpath can point anywhere in the file system. The servlet classpath may contain a directory, a .jar or .zip file, or a URL to a directory.(You cannot specify a URL as a classpath for a zip or jar file.) If the servlet classpath is not a registered servlet directory, you must additionally provide a servlet virtual path translation for it (as discussed in "Configuring Servlet Virtual Path Translations") to make the servlet accessible to clients.

Servlet Args. If the servlet takes additional parameters, enter them here. Separate multiple name=value parameters with a comma. Input must be in the format name=value,name2=value2.... For example, arg1=45, arg2=online, arg3="quick shopping".

http://my_domain.com/plans/plan1

server_id/docs/servlets/plans/releaseA/ planP2Version1A.class

Choose Virtual Path Entry. Specifies a virtual path to modify. If no virtual paths have previously been set up, the list is empty. Upon choosing the virtual path from this drop-down list, the information for the virtual path is displayed in the page. Ignore this field if you are adding a new virtual path entry.

Virtual Path. If you are adding a new path, enter it here. (It's OK to overwrite existing virtual path names.) If you are modifying a path, select the appropriate path from the Choose Virtual Path Entry list to make the path name show up in this field.

Servlet Name. Specifies an identifier for the servlet, as entered in the Configure Servlet Attributes page. It's OK if the servlet identifier has not been specified already, but it must be specified before the virtual path will work.

http://www.javasoft.com/products/jdk/1.2/

JDK Path. Enter the path for the JDK. This is the directory where you installed the JDK.

JDK Runtime Libpath. Enter the runtime library path for the JDK.

JDK Runtime Classpath. The class path includes the paths to the directories and jar files needed to run the servlet engine, the servlet examples, and any other paths needed by servlets that you add. Values are separated by semicolons. You can add new values to the existing class path, but don't delete the existing value since it includes paths that are essential for servlet operation.

JRE Path. Enter the path for the JRE. This is the directory where you installed the JRE.

JRE Runtime Libpath. Enter the runtime library path for the JRE.

• ClassCache

When the server serves a JSP page, it creates a .java and a .class file associated with the JSP and stores them in the JSP class cache, in a directory structure under the ClassCache directory.

• SessionData

If the server uses the MMappedSessionManager session manager, it stores persistent session information in the SessionData directory.

Delete the SessionData Version File . Deletes the version file for the session data. When you apply this change, the version file is deleted immediately. The next time the server starts up, it deletes the session data cache and recreates the version file. The next time the server serves a JSP page or servlet while using the MMappedSessionManager session manager, it recreates the session data cache.

Delete the ClassCache Version File . Deletes the class cache version file for JSP pages. When you apply this change, the version file is deleted immediately. The next time the server starts up, it deletes the JSP class cache and recreates the version file. The next time the server serves a JSP page, it recreates the class cache.

• Overview of CGI
• Specifying a CGI Directory


• Specifying CGI as a File Type


• Downloading Executable Files

• Installing Windows NT CGI Programs
• Installing Shell CGI Programs for Windows NT

• Programmer's Guide for iPlanet Web Server
• The Common Gateway Interface at:

http://hoohoo.ncsa.uiuc.edu/cgi/overview.html

• Articles about CGI available on the online documentation web site at:

http://www.iplanet.com/docs

• Specify a directory that contains only CGI programs. All files are run as programs regardless of the file extensions.
• Specify that CGI programs are all a certain file type. That is, they all use the file extensions .cgi, .exe, or .bat. The programs can be located in any directory in or under the document root directory.

Specifying a CGI Directory
To specify a CGI-only directory, perform the following steps:

1. From the Server Manager, choose the Programs tab.
2. Click the CGI Directory link.

The CGI Directory window appears.

3. In the URL Prefix field, type the URL prefix to use for this directory. That is, the text you type appears as the directory for the CGI programs in URLs.

For example, if you type cgi-bin as the URL prefix, then all URLs to these CGI programs have the following structure:

http://yourserver.domain.com/cgi-bin/program-name

The URL prefix you specify can be different from the real CGI directory you specify in the next step.

• In the CGI Directory text field, type the location of the directory as an absolute path. Note that this directory doesn't have to be under your document root. This is the reason that you need to specify a URL prefix in the previous step.
• Click OK.
• Save and apply your changes.
To remove an existing CGI directory, click that directory's Remove button in the CGI Directory form. To change the URL prefix or CGI directory of an existing directory, click that directory's Edit button.
Copy your CGI programs into the directories you've specified. Remember that any files in those directories will be processed as a CGI file so don't put HTML files in your CGI directory.
Configuring a Unique CGI Directory for Each Software Virtual Server
You can manually configure a unique CGI directory for each software virtual server by manually editing the obj.conf file:

<Object name="default">
.
.
.
<Client urlhost="www.yourvirtualserver.chm">

NameTrans fn="pfx2dir" from="/cgi-bin"

dir="/dir/for/virtual/server/cgi-bin/" name="cgi"

...

</Client>

Note that you can not use the Administration Server to accomplish this task.
Specifying CGI as a File Type
To specify CGI programs as a file type, perform the following steps:

1. From the Server Manager, choose the Programs tab.
2. Click the CGI File Type link.

The CGI as a File Type window appears.

3. From the Resource Picker, choose the resource you want this change to apply to.
4. Click the Yes radio button under Activate CGI as a File Type.
5. Click OK.
6. Save and apply your changes.
The CGI files must have the file extensions .bat, .exe, or .cgi. Any non-CGI files with those extensions are processed by your server as CGI files, causing errors.
Downloading Executable Files
If you're using .exe as a CGI file type, you cannot download .exe files as executables.
One solution to this problem is to compress the executable files that you want users to be able to download, so that the extension is not .exe. This solution has the added benefit of making the download time shorter.
Another possible solution is to remove .exe as a file extension from the magnus-internal/cgi type and add it instead to the application/octet-stream type (the MIME type for normal downloadable files). You can do this through the Server Manager, by choosing the Server Preferences tab and clicking the MIME Types link. However, the disadvantage to this method is that after making this change you cannot use .exe files as CGI programs.
Another solution is to edit your server's obj.conf file to set up a download directory, where any file in the directory is downloaded automatically. The rest of the server won't be affected. For directions on setting up this directory, see the technical note at:

http://help.netscape.com/kb/corporate/19960513-130.html

• Overview of Windows NT CGI Programs
• Specifying a Windows NT CGI Directory
• Specifying Windows NT CGI as a File Type

• The following keywords have been added to the [CGI] section to support security methods:

• HTTPS: its value is on or off, depending on whether the transaction is conducted through SSL.
• HTTPS Keysize: when HTTPS is on, this value reports the number of bits in the session key used for encryption.
• HTTPS Secret Keysize: when HTTPS is on, this value reports the number of bits used to generate the server's private key.
• The keyword Document Root in the [CGI] section might not refer to the expected document root because the server does not have a single document root. The directory returned in this variable is the root directory for the Windows NT CGI program.
• The keyword Server Admin in the [CGI] section is not supported.
• The keyword Authentication Realm in the [CGI] section is not supported.
• Forms sent with multi-part/form-data encoding are not supported.

1. From the Server Manager, choose the Programs tab.
2. Click the Win CGI Directory link.

The WinCGI Directory window appears.

3. In the URL Prefix text field, enter the URL prefix you want to use for this directory.

That is, the text you type appears as the directory for the Windows NT CGI programs in URLs. For example, if you type wcgi-programs as the URL prefix, then all URLs to these Windows NT CGI programs have the following structure:

http://yourserver.domain.com/wcgi-programs/program-name

The URL prefix you specify can be different from the real Windows NT CGI directory you specify in Step 5.

• Choose whether you want to enable script tracing.

Click the Yes or No radio button under "Enable Script Tracing?".

CGI parameters are passed from the server to Windows NT CGI programs through files, which the server normally deletes after the Windows NT CGI program finishes execution. If you enable script tracing, these files are retained in a /temp directory or wherever the environment variables TMP and TEMP are pointing. Also, any window that the Windows NT CGI program brings up is shown when script tracing is enabled.

• In the WinCGI Directory field, enter the location of the directory as an absolute path.

Note that this directory doesn't have to be under your document root. This is the reason that you need to specify a URL prefix in Step 3.

• Click OK.
• Save and apply your changes.
To remove an existing Windows NT CGI directory, click that directory's Remove button in the Windows NT CGI Directory form. To change the URL prefix or Windows NT CGI directory of an existing directory, click that directory's Edit button.
Copy your Windows NT CGI programs into the directories you've specified. Remember that any file in those directories is processed as a Windows NT CGI file.
Specifying Windows NT CGI as a File Type
To specify a file extension for Windows NT CGI files, perform the following steps:

1. From the Server Manager, choose the Server Preferences tab.
2. Click the MIME Types link.

The Global MIME Types window appears. For more information on the Global MIME Types, see the Specifying a Default MIME Type.

3. Add a new MIME type with the following settings:

• Type: type
• Content type: magnus-internal/wincgi.
• File Suffix: Enter the file suffixes that you want the server to associate with Windows NT CGI. If you activated CGI, WinCGI, and shell CGI file types, you must specify a different suffix for each type of CGI. For example, you can't use the suffix .exe for both a CGI program and a shell CGI program. If you need to, you can edit the other MIME type fields on the page so that the suffixes are unique.
4. Click the New Type button.
5. Save and apply your changes.

• Overview of Shell CGI Programs for Windows NT
• Specifying a Shell CGI Directory (Windows NT)
• Specifying Shell CGI as a File Type (Windows NT)

c:\bin\perl.exe hello.pl

1. Create the shell directory on your computer. This directory doesn't have to be a subdirectory of your document root directory.
2. From the Server Manager, choose the Programs tab.
3. Click the Shell CGI Directory link.

The Shell CGI window appears.

4. In the URL Prefix field, enter the URL prefix you want to associate with your shell CGI directory.

For example, suppose you store all shell CGI files in a directory called
C:/docs/programs/cgi/shell-cgi, but you want users to see the directory as http://www.yourserver.com/shell/. In this case, you would type shell as the URL prefix.

Warning.

The server must have read and execute permissions to this directory. For Windows NT, the user account the server runs as (for example, LocalSystem) must have rights to read and execute programs in the shell CGI directory.

1. Create the shell directory on your computer. This directory doesn't have to be a subdirectory of your document root directory.
2. From the Server Manager, choose Server Preferences.
3. Click the MIME Types link.

The Global MIME Types window appears. For more information on the Global MIME Types, see the Specifying a Default MIME Type.

4. Add a new MIME type with these settings:

• Type: type
• Content type: magnus-internal/shellcgi.
• File Suffix: Enter the file suffixes that you want the server to associate with shell CGI. If you activated CGI, WinCGI, and shell CGI file types, you must specify a different suffix for each type of CGI. For example, you can't use the suffix .exe for both a CGI program and a shell CGI program. If you need to, you can edit the other MIME type fields on the page so that the suffixes are unique.
5. Click the New Type button.
6. Save and apply your changes.

You can specify a default query handler CGI program. A query handler processes text sent to it via the ISINDEX tag in an HTML file.

1. From the Server Manager, choose the Programs tab.
2. Click the Query Handler link.

The Query Handler window appears.

3. Use the Resource Picker to select the resource you want to set a default query handler for.

If you choose a directory, the query handler you specify runs only when the server receives a URL for that directory or any file in that directory.

4. In the Default Query Handler field, enter the full path for the CGI program you want to use as the default for the resource you chose.
5. Click OK.
6. Save and apply your changes.

• Activating Server-Side JavaScript
• Running the Application Manager


• Securing the Application Manager


• Installing Server-Side JavaScript Applications


• Application URLs


• Controlling Access to a Server-Side JavaScript Application


• Modifying Installation Parameters


• Removing a Server-Side JavaScript Application


• Starting, Stopping, and Restarting a Server-Side JavaScript Application


• Running a Server-Side JavaScript Application


• Configuring Default Settings

http://www.iplanet.com/docs

1. From the Server Manager, choose the Programs tab.
2. Click the Server Side Javascript link.

The Activate Server Side Javascript window appears.

3. Under Activate the Server Side Javascript application environment, click the Yes radio button.
4. If you want to require the administration server username and password before allowing access to the Application Manager, select the second Yes radio button.

For more information on securing the application manager, see "Securing the Application Manager."

5. Click OK.
6. Save and apply your changes.

• Install a new JavaScript application. You must add an application before users can run it.
• Modify any of the attributes of an installed application (for example, its default home page, path to the .web file, and type of client-object maintenance).
• Stop, start, and restart an installed application.
• Run and debug an active application.
• Remove an installed application.

1. From the Server Manager, choose the Programs tab.
2. Click the Server Side Javascript link.

The Activate Server Side Javascript window appears.

3. Click the link to the Application Manager.
4. Click OK.

You can also run the Application Manager by loading the following URL in Navigator: http://server. domain/appmgr.

iPlanet Web Server displays the following page:

Figure 11.1    The Application Manager






The Application Manager displays all applications currently installed on the server in a scrolling list in the left frame.

5. Select an application by clicking its name in the scrolling list.

For the selected application, the right frame displays the following information:

• The application name at the top of the frame.
• The path of the application .web file on the server. (The .web file is the compiled JavaScript application.)
• The default and initial pages for the application.
• The number of built-in database connections allowed.
• The external libraries used by the application (if any).
• The client object maintenance technique.
• The status of the application: active or stopped. Users can run only active applications. Stopped applications are not accessible.
6. Click the task buttons in the left frame to perform the indicated action on the selected application.

For example, to modify the installation parameters of the selected application, click Modify.

7. Click the Add Application tab at the top to add a new JavaScript application.
8. Click the Preferences tab at the top to configure the default settings to use when adding a new application.

http://server.domain:port/appmgr.

1. From the Server Manager, choose the Programs tab.
2. Click the Server Side Javascript link.

The Activate Server Side Javascript window appears.

3. Under "Require administration server password for Server Side Javascript Application Manager" click the Yes radio button.
4. Click OK.
5. Save and apply your changes.

You must install (add) an application with the Application Manager before you can run it.

1. From the Server Manager, choose the Programs tab.
2. Click the Server Side Javascript link.

The Activate Server Side Javascript window appears.

3. Click the link to the Application Manager.
4. Click the Add Application tab at the top of the page.

The Add Application window appears.

5. In the Name field, type the name of the JavaScript application.

This name defines the application URL. For example, the name of the Hello World application is "world," and its application URL is:

http://server.domain:port/world

This is a required field, and the name you type must be different from all other application names on the server. The name must include only alphanumeric characters and cannot include spaces. For more information on application URLs, see "Application URLs."

6. In the Web File Path field, type the absolute path to the .web file for the application.

This is a required field.

7. In the Default Page field, note what file to send to a client who does not indicate a specific page for the application.

This page is analogous to index.html for a standard URL. This is a required field.

8. In the Initial Page field, specify a page to run when the application is first started.

This page only runs once during the life of the application and is used to initialize values and establish database connections. This is an optional field.

In the Built-in Maximum Database Connections field, specify the maximum number of database connections that this application can have at one time if you are using the built-in database object. (This is provided for backward compatibility with applications that use database objects; for new applications that use a dbpool, ignore this field. See Chapter 8, "Connecting to a Database," in the Server-Side JavaScript Guide for how to set this parameter for a dbpool.)

9. In the External Libraries field, specify the absolute paths of any libraries to be used with the application.

This is an optional field. Libraries installed for one application can be used by all applications on the server.

10. In the Client Object Maintenance field, specify the mode for maintaining the client object. For additional information on client objects, refer to Writing Server-Side JavaScript Applications at:

http://www.iplanet.com/docs

The choices for the client object maintenance technique are:

• client-cookie—Specifies that the JavaScript runtime engine on the server should use the Netscape cookie protocol to transfer the properties of the client object and their values to the client. It creates one cookie per client property. The properties are sent to the client once, in the response header of the generated HTML page.
• client-url—Specifies that the runtime engine on the server should transmit the properties of the client object and their values to the client by appending them to each URL in the generated HTML page. Consequently, the properties and their values are sent as many times as there are links on the generated HTML page, resulting in the largest increase in network traffic of all of the maintenance techniques.
• server-ip—Specifies that the server should index the data structure based on the application and the client's IP address. This technique is the fastest, because it does not require sending any information to the client. Since the index is based on both the application and the IP address, this technique creates a separate index for every application/client pair running on the server.
• server-cookie—Specifies that the server should use a long unique name, generated by the runtime engine, to index the data structure on the server. The runtime engine uses the Netscape cookie protocol to store the generated name as a cookie on the client. It does not store the property names and values as cookies. For this reason, this technique creates a single cookie, whereas the client-cookie technique creates a separate cookie for each property of the client object.
• server-url—Specifies that the server should use a long unique name, generated by the runtime engine, to index the data structure on the server. In this case, rather than making that generated name be a cookie on the client, the server appends the name to each URL in the generated HTML page. Consequently, the name is sent as many times as there are links on the generated HTML page. (Property names and values are not appended to URLs, just the generated name.)
11. After you have entered all the required information, click OK to install the application, Reset to clear all the fields, or Cancel to cancel the operation.

Application URLs
When you install a Server-Side JavaScript application, you must enter a name for it. This name determines the application URL, the URL that clients use to access a JavaScript application. Application URLs are of the form

http://server.domain:port/appName/page.html

http://server.domain:port/appName/

http://myserver.mozilla.com/world/hello.html

http://myserver.mozilla.com/world/

Using the previous example, any requests for URLs that begin with
http://myserver.mozilla.com/world will look for documents in the js/samples/world directory and not in your server's normal document root.

http://server.domain:port/appmgr/ control.html?name=appName&cmd=action

• Open the Application Manager as described in "Running the Application Manager," then select the application name in the Application Manager, and click Run. A new Navigator window accesses the application.
• Enter the application URL in Navigator.

• Installation parameters: .web file path, default page, initial page, maximum number of built-in database connections, external libraries, and client object maintenance technique. You can specify a default directory path for your development area and native executables libraries.
• Whether you are prompted to confirm your action when you remove, start, stop, or restart an application.
• When debugging an application, whether the application trace appears in the same window as the application but in another frame, or in a window separate from the application.

WAI services are a kind of plug-in that uses the Common Object Request Broker Architecture (CORBA). WAI applications can be written in C, C++, or Java, and they interact with iPlanet Web Server over Internet Inter-ORB Protocol (IIOP). A WAI application runs within its own process. WAI applications need an object request broker (ORB) to work.

http://www.inprise.com/products/

1. From the Server Manager, choose the Programs tab.
2. Click the WAI Handler link.

The WAI Administration window appears.

3. To enable WAI services, click the Yes radio button.
4. Save and apply your changes.

http://www.iplanet.com/docs