Previous     Contents     Index     Next     
iPlanet Web Server: FastTrack Edition Administrator's Guide



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

This chapter includes the following sections:



Overview of Server-Side Programs

Java servlets, JavaScript applications, and CGI programs have different strengths and uses. The following list illustrates the differences between these server-side programs:

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


    Caution

    		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.


    Note iPlanet Web Server 4.1 does not support server-side Java applets.



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

The iPlanet Web Server can also run programs that extend or modify the behavior of the server itself. These programs, known as plug-ins, are written using the Netscape Server Application Programming Interface (NSAPI). For information about writing and installing plug-in programs, see the NSAPI Programmer's Guide for iPlanet Web Server.


How Server-Side Applications Are Installed on the Server

Each type of program is installed onto the server differently. The following list summarizes the procedures:

These installation procedures are described in the following sections.



Java Servlets and JavaServer Pages (JSP)


This section discusses how to install and use Java Servlets and JavaServer Pages on iPlanet Web Server.

This section describes the following topics:


Overview of Servlets and JavaServer Pages

iPlanet Web Server supports Java servlets and JavaServer Pages (JSP).

Java servlets are server-side Java programs that can be used to extend the functionality of a web server in much the same way as CGI programs do. Servlets can be thought of as applets that run on the server side without an interface. Servlets are invoked through URL invocation. iPlanet Web Server includes support for JavaSoft's Servlet API at the level of the Java Servlet Development Kit (JSDK) 2.2.1PR.

To develop servlets, use Sun Microsystems' Java Servlet API. For information about using the Java Servlet API, see the documentation provided by Sun Microsystems at:

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

For information about developing servlets for use with iPlanet Web Server, see Programmer's Guide to Servlets in iPlanet Web Server.

A JavaServer Page (JSP) is a page, much like an HTML page, that can be viewed in a web browser. However, as well as containing HTML tags, it can include a set of JSP tags that extend the ability of the web page designer to incorporate dynamic content in a page. These tags provide functionality such as displaying property values and using simple conditionals. iPlanet Web Server supports JavaServer Pages (JSP) to the level of JSP API 1.0 compliance.

For information about creating JavaServer Pages, see Sun Microsystem's JavaServer Pages web page at:

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


What the Server Needs to Run Servlets and JSPs

iPlanet Web Server includes the Java Runtime Environment (JRE) but not the Java Development Kit (JDK). The server can run servlets using the JRE, but it needs the JDK to run JSP. If you want to run JSP, you must tell iPlanet Web Server to use a custom JDK.

iPlanet Web Server 4.1 requires you to use official versions of JDK, with different platforms requiring different versions, as summarized in Table 9-1.


Table 9-1 Supported JavaSoft JDK Versions by Platform

Platform

JRE/JDK Version

Solaris Sparc  

1.2.2_01  

Windows NT  

1.2.2_01  

HPUX  

1.2.2_02  

AIX  

1.2.1  

Compaq  

1.2.2-3  

Linux  

1.2.2RC4  

IRIX  

1.2.1  

Check the iPlanet Web Server Installation and Migration Guide and the latest Release Notes for updates on required JDK versions.

JDK 1.2 (and other JDK versions) are available from Sun Microsystems at:

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

You can specify the path to the JDK in either of the following ways:

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

Whether you specify the path to the JDK during installation or later, the path is the folder in which you installed the JDK.


Enabling Servlets and JSP

Before iPlanet Web Server can run servlets, the servlet engine must be enabled. Before the server can serve JSP, the servlet engine must be enabled and JSP must be enabled. (The server cannot serve JSP if servlets are not enabled.)

To enable and disable servlets and JSP in iPlanet Web Server, use the Enable/Disable Servlets/JSP page in the Servlets tab in the Server Manager. This page lets you enable or disable servlets and also enable or disable JSP. If servlets are disabled, you cannot enable JSP.

If servlets are enabled, JSP can be enabled or disabled. However, if you disable servlets, JSP is automatically also disabled. In this case, if you enable servlets later, you must re-enable JSP also if desired.

You can also define a thread pool to be used for servlets. For any server subsystem you can specify which thread pool the servlet's going to run on. For more information about thread pools, see Adding and Using Thread Pools.


Making JSPs Available to Clients

You can install JSP files simply by putting them in any directory in or under the document root—you do not need to do anything special to install JSP files—so long as the following conditions are true:

  • iPlanet Web Server has been instructed to use the JDK.

  • Both servlets and JSP are enabled in the server.


Making Servlets Available to Clients

For servlets, you have a choice of two ways to make a servlet accessible to clients:

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

You can choose both these options. You can specify a servlet directory and define servlet virtual path translations for servlets outside the servlet directory.


Specifying Servlet Directories

One of the ways to make a servlet accessible to clients is to put it into a directory that has been registered with iPlanet Web Server as a servlet directory. Servlets in registered servlet directories are dynamically loaded when needed. The server monitors the servlet files and automatically reloads them on the fly as they change.

For example, if the SimpleServlet.class servlet is in the servlet subdirectory of the server's document root directory, you can invoke the servlet by pointing the web browser to:

http://your_server/servlet/SimpleServlet

You can register any number of servlet directories for iPlanet Web Server. Initially, the web server has a single servlet directory per server instance, which is server_id/docs/servlet/.

iPlanet Web Server expects all files in a registered servlet directory to be servlets. Any files, including applets, in that directory that have the .class extension will be treated as servlets. iPlanet Web Server does not correctly serve other files, such as HTML files or JSPs, that reside in that directory.

The server can have multiple servlet directories, all of which must reside below the primary document directory in the directory hierarchy. You can map servlet directories to virtual directories if desired. For example, you could specify that http://my_domain.com/products/ invokes servlets in the directory server_id/docs/servlet/january/products/servlets/.

To register servlet directories and to specify their URL prefixes (virtual or not), use the Servlet Directory page in the Servlets tab of the Server Manager. Set the following fields:

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.


Note By default, URLs that are redirected are always escaped. To prevent this, add escape="no". For example:

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



Configuring Global Attributes

You can set some global attributes for servlets, including:

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

To set the global attributes, use the "Configure Global Servlet Attributes" page in the Servlets tab of the Server Manager. Set the following fields:

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.


Configuring Servlet Attributes

If you want to specify input parameters, class paths, or virtual translations for a servlet, you need to individually configure the servlet. Do this in the Configure Servlet Attributes page of the Servlets tag in the Server Manager.


Note When you configure a servlet through the Configure Servlet Attributes page, the servlet is automatically added to the servlets.properties file in iPlanet Web Server's config directory.


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.

iPlanet Web Server supports the specification of multiple directories, jars, zips, and URLs in the servlet classpath.

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


Configuring Servlet Virtual Path Translations

One way to make servlets available to clients is to put them in registered servlet directories. Another way is to define servlet virtual path translations for individual servlets. For example, you could specify that the URL:

http://my_domain.com/plans/plan1

invokes the servlet defined in

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

You can set up servlet virtual path translations for servlets that reside anywhere, on a local or remote file system, or in or out of a registered servlet directory.

Before setting up a servlet virtual path translation, the servlet must have been configured in the Configure Servlet Attributes page of the Servlets tab in the Server Manager, as discussed in "Configuring Servlet Attributes."

To specify a servlet virtual translation path, use the Configure Servlet Virtual Path Translation page in the Servlets tab in the Server Manager. This page has the following fields:

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.

The value to enter here is the URL for the virtual path without the
http://servername part. For example, if you want the virtual path to be http://servername/virtual/tracker, enter /virtual/tracker.

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.


Configuring JRE/JDK Paths

When you install iPlanet Web Server, you can choose to install the Java Runtime Environment (JRE) or you can specify a path to the Java Development Kit (JDK).

The server can run servlets using the JRE, but it needs the JDK to run JSP. The JDK is not bundled with iPlanet Web Server, but you can download it for free from Sun Microsystems at:

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

Regardless of whether you choose to install the JRE or specify a path to the JDK during installation, you can tell the iPlanet Web Server to switch to using either the JRE or JDK at any time. 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.

Supply values for the following fields if you select the JDK radio button:

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.

Supply values for the following fields if you select the JRE radio button:

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.


Note If you are not sure of the JDK runtime libpath, the JDK runtime classpath, or the JRE runtime libpath, leave these fields blank to tell the server to use default paths.



Configuring JVM Attributes

You can configure attributes for the Java Virtual Machine (JVM) in the Configure JVM page of the Servlets tab in the Server Manager.

For more information on these options, see Programmer's Guide to iPlanet Web Server.


Deleting Version Files

The server uses two directories to cache information for JavaServer Pages (JSP) and servlets:

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

Each cache has a version file containing a version number that the server uses to determine the structure of the directories and files in the caches. You can clean out the caches by simply deleting the version file.

When the server starts up, if it does not find the version files, it deletes the directory structure for the corresponding caches and re-creates the version files. Next time the server serves a JSP page, it recreates the JSP class cache. The next time the server serves a JSP page or servlet while using MMappedSessionManager session manager, it recreates the session data cache.

If a future upgrade of the server uses a different format for the caches, the server will check the number in the version file and clean up the caches if the version number is not correct.

The Delete Version Files page allows you to delete the files that contain the version number for the JavaServer Pages class cache and the session data cache. This page has the following fields:

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.



Installing CGI Programs


This section discusses how to install CGI programs. It has the following sub-sections:

In addition, the following sections discuss how to install Windows NT-specific CGI programs:


Overview of CGI

Common Gateway Interface (CGI) programs can be defined with any number of programming languages. On a Unix/Linux machine, you're likely to find CGI programs written as Bourne shell or Perl scripts.

Note Under Unix/Linux, there are extra CGIStub processes running that the server uses to aid in CGI execution. These processes are created only during the first access to a CGI. Their number varies depending upon the CGI load on the server. Do not kill these CGIStub processes. They disappear when the server is stopped.


On a Windows NT computer, you might find CGI programs written in C++ or batch files. For Windows NT, CGI programs written in a Windows-based programming language such as Visual Basic use a different mechanism to operate with the server. They are called Windows NT CGI programs. See "Installing Windows NT CGI Programs" for information about Windows NT CGI.


Note In order to run the command-line utilities, you need to manually set the Path variable to include server_root/bin/https/bin.


Regardless of the programming language, all CGI programs accept and return data in the same manner. For information about writing CGI programs, see the following sources of information:

There are two ways to store CGI programs on your server machine:

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

You can enable both options at the same time if desired.

There are benefits to either implementation. If you want to allow only a specific set of users to add CGI programs, keep the CGI programs in specified directories and restrict access to those directories. If you want to allow anyone who can add HTML files to be able to add CGI programs, use the file type alternative. Users can keep their CGI files in the same directories as their HTML files.

If you choose the directory option, your server attempts to interpret any file in that directory as a CGI program. By the same token, if you choose the file type option, your server attempts to process any files with the file extensions .cgi, .exe, or .bat as CGI programs. If a file has one of these extensions but is not a CGI program, an error occurs when a user attempts to access it.


Caution

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



Note By default, the file extensions for CGI programs are .cgi, .exe and .bat. However, you can change which extensions indicate CGI programs by modifying the MIME types file. You can do this by choosing the Server Preferences tab and clicking the MIME Types link.



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


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


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

  5. Click OK.

  6. 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/server/960513-130.html



Installing Windows NT CGI Programs

This section discusses how to install Windows NT CGI Programs. The following topics are included in this section:


Overview of Windows NT CGI Programs

Windows NT CGI programs are handled much as other CGI programs. You specify a directory that contains only Windows NT CGI programs, or you specify that all Windows NT CGI programs have the same file extension. Note that like other CGI programs, you can use both methods at the same time if you want to. For example, you can create a directory for all your Windows NT CGI programs, and specify a Windows NT CGI file extension.

Although Windows NT CGI programs behave like regular CGI programs, your server processes the actual programs slightly differently. Therefore, you need to specify different directories for Windows NT CGI programs. If you enable the Windows NT CGI file type, it uses the file extension .wcg.

iPlanet Web Servers support the Windows NT CGI 1.3a informal specification, with the following differences:

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


Specifying a Windows NT CGI Directory

To specify a Windows NT CGI-only directory:

  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


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


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

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

  6. Click OK.

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



Installing Shell CGI Programs for Windows NT

This section discusses how to install Shell CGI Programs for Windows NT. The following topics are included in this section:


Overview of Shell CGI Programs for Windows NT

Shell CGI is a server configuration that lets you run CGI applications using the file associations set in Windows NT.

For example, if the server gets a request for a shell CGI file called hello.pl, the server uses the Windows NT file associations to run the file using the program associated with the .pl extension. If the .pl extension is associated with the program C:\bin\perl.exe, the server attempts to execute the hello.pl file as follows:

c:\bin\perl.exe hello.pl

The easiest way to configure shell CGI is to create a directory in your server's document root that contains only shell CGI files. However, you can also configure the server to associate specific file extensions with shell CGI by editing MIME types from the iPlanet Web Server.


Note For information on setting Windows NT file extensions, see your Windows NT documentation.



Specifying a Shell CGI Directory (Windows NT)

To create a directory for your shell CGI files, perform the following steps:

  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.

  5. In the Shell CGI Directory field, enter the absolute path to the directory you created.


    Caution

    		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.


  6. Make sure that any files in the shell CGI directory also have file associations set in Windows NT. The server returns an error if it attempts to run a file that has no file-extension association.


Specifying Shell CGI as a File Type (Windows NT)

You can use the iPlanet Web Server's MIME Types window to associate a file extension with the shell CGI feature. This is different from creating an association in Windows NT.

To associate a file extension with the shell CGI feature in the server, for example, you can create an association for files with the .pl extension. When the server gets a request for a file with that extension, the server knows to treat the file as a shell CGI file by calling the executable associated in Windows NT with that file extension.

To associate a file extension as a shell CGI file, perform the following steps:

  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.



Using the Query Handler


Note The use of Query Handlers is outdated. Although iPlanet Web Server and Netscape Navigator clients still support it, it is rarely used. It is much more common for people to use forms in their HTML pages to submit queries.


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.

ISINDEX is similar to a form text field in that it creates a text field in the HTML page that can accept typed input. Unlike the information in a form text field, however, the information in the ISINDEX box is immediately submitted when the user presses Return. When you specify your default query handler, you tell your server to which program to direct the input. For an in-depth discussion of the ISINDEX tag, see an HTML reference manual.

To set a query handler, perform the following steps:

  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.



Server-Side JavaScript Programs

To allow iPlanet Web Server to run Server-Side JavaScript programs, you need to enable Server-Side JavaScript, which you can do in the Activate Server Side JavaScript page in the Programs tab of the Server Manager.

To install and manage Server-Side JavaScript programs on the server, use the JavaScript Application Manager.

The following topics are included in this section:

For more information about writing JavaScript applications, see Writing Server-Side JavaScript Applications at:

http://www.iplanet.com/docs


Activating Server-Side JavaScript

To enable Server-Side JavaScript on iPlanet Web Server, perform the following steps:

  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.


Running the Application Manager

For applications written in Server-Side JavaScript, you can perform many administrative tasks with the Server-Side JavaScript Application Manager. Using the Application Manager, you can do the following:

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

To run the Application Manager, perform the following steps:

  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 9-1    The Application Manager

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

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

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

  3. Click the Add Application tab at the top to add a new JavaScript application.

  4. Click the Preferences tab at the top to configure the default settings to use when adding a new application.


Securing the Application Manager

The Application Manager runs on iPlanet Web Server. It is installed into the js/appmgr directory. It can be accessed with the URL:

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

Consequently, you may want to restrict access to the Application Manager URL and the application URI so that only you and any other trusted administrators can access them. If you don't restrict access to the Application Manager, anyone can add, remove, modify, start, and stop applications on your server.

If you want to require the administration server username and password for access to the Application Manager, perform the following steps:

  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.

If your server does not use the Secure Sockets Layer (SSL), the username and password for the Application Manager are transmitted unencrypted over the network. Any intruder who intercepts this data may be able to access the Application Manager. If you use the same password for your administration server, the intruder can also control your server. For security reasons, do not use the Application Manager from outside your firewall unless you are using SSL.


Installing Server-Side JavaScript Applications

You can install up to 120 JavaScript applications on one server.

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

To install a new application, perform the following steps:

  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 iPlanet Web Server 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.


    Note Don't give any JavaScript applications the same names as any subdirectories of your primary document directory. If you do, the server will no longer correctly process requests for resources in the directory. For example, if you have a directory server_root/docs/bug, and a JavaScript application named bug, all requests for any files in the bug directory (or any of its subdirectories) will attempt to launch the JavaScript application bug. The JavaScript application URI takes precedence.



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

where server is the name of the HTTP server, domain is the Internet domain (including any subdomains), port is the port number of the HTTP server, appName is the application name you enter when you install it, and page is the name of a page in the application, such as the default page name.

You can also access the application with the URL

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

since the server knows the default page to open.

For example, if your server is named myserver and your domain name is mozilla.com, the application name is world, and the default page is hello.html, you can access the application with either of the following URLs:

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

or

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

When a client requests an application URL, the server runs the Server-Side JavaScript code inside the default page then sends the resultant HTML page to the client.


Important
Before you install an application, make sure the application name you choose does not usurp an existing URL on your server. All client requests for URLs that match the application URL are routed to the directory specified for the .web file, circumventing the server's normal document root.

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.


Controlling Access to a Server-Side JavaScript Application

When you install an application, you may want to restrict its use to only certain users. You can do this by applying a configuration style to the application. For more information, see Working With Configuration Styles For more information on restricting access to part of your server, see Controlling Access to Your Server


Modifying Installation Parameters

To modify an application's installation parameters, open the Application Manager as described in the section "Running the Application Manager." Then select the application name in the left frame of the Application Manager and click Modify.

You can change any of the parameters defined when you installed the application except the application name. To change the name of an application, you must remove the application and then reinstall it.

If you modify the parameters of a stopped application, the Application Manager automatically starts it. When you modify parameters of an active application, Application Manager automatically stops and restarts it.


Removing a Server-Side JavaScript Application

To remove the selected application, open the Application Manager as described in "Running the Application Manager," then click Remove. This action removes the application from the Application Manager but does not delete files from the server. At this point, clients can no longer access the application.

If you delete an application and you subsequently want to run it, you must install it again.


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

To start an installed application that is stopped, open the Application Manager as described in "Running the Application Manager," and then click Start. If the application starts successfully, clients can invoke the application.

To stop an active application, click Stop. The application's status changes to "stopped," and clients can no longer invoke the application. You must stop an application if you want to move the .web file or update an application from a development server to a deployment server.

To restart a running application, click Restart. Before any changes take effect, you must restart an application after you compile it.

You can also start, stop, and restart an application by entering a special URL of the form:

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

where appName is the application name and action is either stop, start, or restart.


Running a Server-Side JavaScript Application

There are two ways to run an installed application:

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

If you attempt to run a stopped application (one that is not active), then the Application Manager tries to start it first.


Configuring Default Settings

To configure default settings for new applications, open the Application Manager as described in "Running the Application Manager," and then click the Preferences tab. When you install a new application, the default installation parameters are used for the initial settings.

You can specify the following default settings:

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



Enabling WAI Services


Note Web Application Interface (WAI) is provided in iPlanet Web Server 4.x, but is not guaranteed to be supported in future releases. We recommend that you do not develop new WAI applications.


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.

iPlanet Web Server 4.x does not ship with an object request broker (ORB). Before using WAI applications, you must install Visibroker 3.3+ from Inprise. You can get Visibroker3.3+ from the Inprise web site at:

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

After installing Visibroker 3.3+, you will need to install WAI on your iPlanet Web Server. You can do this by running through the installation process, and choosing to install only WAI.

After you have installed WAI, the next step is to enable it on your server. Enabling WAI services essentially turns on Internet Inter-ORB Protocol (IIOP) support in the server.

To enable WAI services on your server, perform the following steps:

  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.

For more information about WAI, see Writing Web Applications with WAI at:

http://www.iplanet.com/docs


Previous     Contents     Index     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated July 13, 2000