Netscape logo Administrator's Guide
Netscape Enterprise Server
Previous      Contents      Index      Next     

Chapter 13   Extending Your Server With Programs


This chapter discusses how to install programs on the Netscape Enterprise 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 and CGI programs have different strengths and uses. The following list illustrates the differences between these server-side programs:

Types of Server-Side Applications That Run on the Server

The Enterprise Server can run the following types of server-side applications to dynamically generate content:

The Enterprise 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 Netscape Enterprise Server NSAPI Programmer's Guide.

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 PagesTM on Enterprise Server.

The following topics are described:

Overview of Servlets and JavaServer Pages

Enterprise Server 6.1 supports the Servlet 2.3 API specification, which allows servlets and JSPs to be included in web applications.

A web application is a collection of servlets, JavaServer Pages, HTML documents, and other web resources which might include image files, compressed archives, and other data. A web application may be packaged into an archive (a WAR file) or exist in an open directory structure.

Note  

Servlet API version 2.3 is fully backward compatible with versions 2.2 and 2.1, so all existing servlets will continue to work without modification or recompilation.



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

http://java.sun.com/products/servlet/index.html

A JSP is a page, much like an HTML page, that can be viewed in a web browser. However, in addition to HTML tags, it can include a set of JSP tags and directives intermixed with Java code that extend the ability of the web page designer to incorporate dynamic content in a page. These additional features provide functionality such as displaying property values and using simple conditionals. Enterprise Server 6.1 supports the JavaServer Pages (JSP) 1.1 API specification.

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

http://java.sun.com/products/jsp/index.html

For information about developing servlets and JSPs for use with Enterprise Server, see the Netscape Enterprise Server Programmer's Guide to Servlets.

What the Server Needs to Run Servlets and JSPs

To enable servlets, select the Java tab in the Server manager, then select the Enable/Disable Servlets/JSP tab. Check the Enable Java Globally box to enable servlets for the entire server. Check the Enable Java for Class box to enable servlets for a single virtual server class. You cannot enable servlets for a class unless Java is globally enabled. By default, Java is globally enabled and enabled for each virtual server class.

To enable JSPs, first enable servlets. You must also include the jsp-servlet element with enable="true" in the web-apps.xml file and add tools.jar to the JVM classpath. For more information, see the Netscape Enterprise Server Programmer's Guide to Servlets.

Enterprise Server includes the Java Runtime Environment (JRE) but not the Java Development Kit (JDK). The server can run servlets and precompiled JSPs using the JRE, but it needs the JDK to run uncompiled JSPs. If you want to develop JSPs, you must tell Enterprise Server to use a custom JDK.

Enterprise Server requires you to use official versions of JDK, with different platforms requiring different versions, as summarized in the Netscape Enterprise Server Programmer's Guide to Servlets.

Check the Netscape Enterprise Server Installation and Migration Guide and the Netscape Enterprise Server Release Notes for updates on required JDK versions.

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

http://java.sun.com/products/jdk/1.2/

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

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

Working with Web Applications

The following sections describe how to deploy, edit, and delete web applications either manually by using the wdeploy command line utility, or through the user interface.

Using the web-apps.xml File

Before you deploy web applications, you must modify the web-apps.xml file, which is specific to Enterprise Server. Each virtual server has its own web-apps.xml file, which defines contexts for a set of web applications running in that virtual server. The context information includes a context path of the web application and other properties such as how it handles session management or authentication.

Once deployed, your web applications are enabled by default. To disable a deployed web application manually you would need to modify the web-app.xml file as follows:

<vs>
<web-app uri="/mywebapp" dir="/webappdir" enable = "false" >
</web-app>
 

If you inadvertently deploy or edit more than one web application with the same description, and one of them is disabled, the server will ignore enable = "false" and continue with default setting of enable = "true".

For more information about the web-apps.xml file, see the Netscape Enterprise Server Programmer's Guide to Servlets.

Deploying Web Applications Using wdeploy

Before you can deploy a web application manually, you must make sure that the server_root/bin/https/httpsadmin/bin directory is in your path and that the NES_SERVER_HOME environment variable is set to your server_root directory.

You can use the wdeploy utility at the command line to deploy a WAR file into a virtual server web application environment:

wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_file -n

You can also delete a virtual server web application:

wdeploy delete -u uri_path -i instance -v vs_id mode -n

You can also list the web application URIs and directories for a virtual server:

wdeploy list -i instance -v vs_id

The command parameters have the following meanings:

uri_path

The URI prefix for the web application.

instance

The server instance name.

vs_id

The virtual server ID.

directory

(optional) The directory to which the application is deployed, or from which the application is deleted. If not specified for deployment, the application is deployed to the document root directory.

mode

Valid values are hard or soft. Specifies whether the directory and the web-apps.xml entry are deleted (hard) or just the web-apps.xml entry is deleted (soft).

war_file

The WAR file name

Caution  

If you deploy a web application and do not specify a directory, the application is deployed to the document root directory. If you then delete the application using the hard parameter, the document root directory will be deleted.



When you execute the wdeploy deploy command, three things happen:

For example:

wdeploy deploy -u /hello -i server.example.com -v netscape.com -d /nes61/https-server.example.com/netscape.com/web-apps/hello /nes61/plugins/servlets/examples/web-apps/HelloWorld/HelloWorld.war

This utility results in the following web-apps.xml entry:

<vs>
   <web-app uri="/hello" dir="/nes61/https-server.example.com/netscape.com/webapps/hello"/>
</vs>

The /nes61/https-server.example.com/netscape.com/web-apps/hello directory has the following contents:

colors
index.jsp
META-INF
WEB-INF/
   web.xml
   /classes/
      HelloWorldServlet.class
      HelloWorldServlet.java
      SnoopServlet.class
      SnoopServlet.java

Using -n in the wdeploy Command

In a previous release of Enterprise Server, after deploying or deleting a web application, wdeploy dynamically reconfigures the server, causing the server to load or unload the web application that was deployed or deleted. Previously, you had to explicitly reconfigure the server in order for your changes to take effect by doing one of the following:

Now a successful wdeploy command will automatically be enabled to service requests for a new web application, or to stop servicing requests for a deleted web application.

The -n option prevents wdeploy from automatically sending the reconfigure command to the web server. Use the -n option in your command when deploying or undeploying multiple web applications (in a script for example), and you want to reconfigure the server only once after the last web application is deployed.

Accessing Deployed Web Applications

After you have deployed an application, you can access it from a browser as follows:

http[s]://vs_urlhost[:vs_port]/uri_path/[index_page]

The parts of the URL have the following meanings:

vs_urlhost

One of the urlhosts values for the virtual server.

vs_port

(optional) Only needed if the virtual server uses a non-default port.

uri_path

The same one you used to deploy the application. This is also the context path.

index_page

(optional) The page in the application that end users are meant to access first.



For example:

http://example.com:80/hello/index.jsp

or:

http://example.com/hello/

Deploying and Editing Web Applications with the User Interface

You can deploy, edit, delete, disable, and enable web applications for a specified virtual server.

Deploying Web Applications

You can access the Deploy Web Applications page by selecting Deploy Web Applications under the Web Applications tab of the Virtual Server Manager.

To deploy a web application, follow these steps:

  1. Enter the Path to the web application file in the Web Applications File field. This is set to web-apps.xml for the default virtual server. The path can be an absolute path or a file name in the configuration directory of the instance. If the file does not exist there, it will be created.
  2. Select Local Machine or Server Machine from the WAR File On drop-down list.
    3. Select Local Machine when uploading a WAR file to your server. Select Server Machine when the WAR file already resides there.
     
  3. Enter the path on the local or server machine to the WAR file containing the web application in the field provided.
    4. On server machines enter the absolute path to the WAR file.
     
    On local machines you can browse the available paths. Clicking browse will bring up the File Upload window, allowing you to select the WAR file to upload to your server.
     
  4. Enter the URI on the virtual server for the web application in the field provided.
  5. Enter the absolute path to the directory on the server machine where the contents of the WAR file will be extracted to. If the directory does not exist, one will be created.
  6. Click OK.
  7. Click Apply.
  8. Select Dynamic Reconfiguration for your web application to be deployed.

Editing Web Applications

You can edit, delete, disable, or enable an already deployed web application. Access the Edit Web Applications page by selecting Edit Web Applications under the Web Applications tab of the Virtual Server Manager.

To edit, delete, disable, or enable an already deployed web application, follow these steps:

  1. Select the action you wish to perform from the drop-down list in the Action column next to the web application you are editing. Choose:
  2. (Optional) Enter a new URI in the URI field if you are editing the web application.
  3. Click OK.
  4. Click Apply.
  5. Select Dynamic Reconfiguration for your web application to be deployed.

Deploying Servlets and JSPs Not in Web Applications

You can deploy 4.x servlets and JSPs outside of web applications, but only in the default virtual server. For information, see the Netscape Enterprise Server Programmer's Guide to Servlets.

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 the Netscape Enterprise Server Programmer's Guide to Servlets.

Deleting Version Files

The Delete Version Files page on the Java tab of the Server Manager allows you to delete the files that contain the version numbers for the JavaServer Pages class cache and the session data cache. This page has the following fields:

Clear Session Data

Deletes the SessionData directory, which stores persistent session information if the server uses the MMapSessionManager session manager.

Delete JSP ClassCache Files

Deletes the ClassCache directory, which caches information for JavaServer Pages (JSP). The default location of this directory is:

server_root/https-identifier/ClassCache/virtual_server_id/webapp_uri/

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 under the ClassCache directory.

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

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.

Installing CGI Programs

This section discusses how to install CGI programs. The following topics are described:

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

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/Windows 2000 computer, you might find CGI programs written in C++ or batch files. For Windows NT/Windows 2000, 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/Windows 2000 CGI programs. See "Installing Windows NT/Windows 2000 CGI Programs" for information about Windows NT/Windows 2000 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:

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.

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 for a class of virtual servers, perform the following steps:

  1. From the Class Manager, choose the Programs tab.
    2. The CGI Directory window appears.
     
  2. 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.
    3. 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.dom][:port]/cgi-bin/program-name
     

    Note  

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



  3. 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 next step.
  4. Click OK.
  5. 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 CGI files, so don't put HTML files in your CGI directory.

Configuring Unique CGI Attributes for Each Software Virtual Server

To specify CGI attributes for a single virtual server, perform the following steps:

  1. From the Class Manager, choose the Manager Virtual Servers button.
  2. From the Virtual Server Manager, choose the Settings tab.
  3. In the CGI User text field, type the name of the user to execute CGI programs as.
  4. In the CGI Group text field, type the name of the group to execute CGI programs as.
  5. In the CGI Directory text field, type the directory to chdir to after chroot but before execution begins.
  6. (UNIX only) In the CGI Nice text field, type an increment that determines the CGI program's priority relative to the server. Typically, the server is run with a nice value of 0 and the nice increment would be between 0 (the CGI program runs at same priority as server) and 19 (the CGI program runs at much lower priority than server). While it is possible to increase the priority of the CGI program above that of the server by specifying a nice increment of -1, this is not recommended.
  7. In the Chroot Directory text field, type the directory to chroot to before execution begins.
  8. Click OK.
  9. Save and apply your changes.

Specifying CGI as a File Type

To specify CGI programs as a file type, perform the following steps:

  1. From the Class Manager, choose the Programs tab.
  2. Click the CGI File Type page.
    3. The CGI as a File Type window appears.
     
  3. From the Editing 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.

Installing Windows NT/Windows 2000 CGI Programs

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

Overview of Windows NT/Windows 2000 CGI Programs

Windows NT/Windows 2000 CGI programs are handled much as other CGI programs. You specify a directory that contains only Windows NT/Windows 2000 CGI programs, or you specify that all Windows NT/Windows 2000 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/Windows 2000 CGI programs, and specify a Windows NT/Windows 2000 CGI file extension.

Although Windows NT/Windows 2000 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/Windows 2000 CGI programs. If you enable the Windows NT/Windows 2000 CGI file type, it uses the file extension .wcg.

Enterprise Servers support the Windows NT/Windows 2000 CGI 1.3a informal specification, with the following differences:

Specifying a Windows NT/Windows 2000 CGI Directory

To specify a Windows NT/Windows 2000 CGI-only directory:

  1. From the Class Manager, choose the Programs tab.
  2. Click the WinCGI Directory link.
    3. The WinCGI Directory window appears.
     
  3. In the URL Prefix text field, enter the URL prefix you want to use for this directory.
    4. That is, the text you type appears as the directory for the Windows NT/Windows 2000 CGI programs in URLs. For example, if you type wcgi-programs as the URL prefix, then all URLs to these Windows NT/Windows 2000 CGI programs have the following structure:
     
    http://yourserver[.domain.dom][:port]/wcgi-programs/program-name
     

    Note  

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



  4. Choose whether you want to enable script tracing.
    5. Click the Yes or No radio button under "Enable Script Tracing?".
     
    CGI parameters are passed from the server to Windows NT/Windows 2000 CGI programs through files, which the server normally deletes after the Windows NT/Windows 2000 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/Windows 2000 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.
    6. 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/Windows 2000 CGI directory, click that directory's Remove button in the Windows NT/Windows 2000 CGI Directory form. To change the URL prefix or Windows NT/Windows 2000 CGI directory of an existing directory, click that directory's Edit button.

Copy your Windows NT/Windows 2000 CGI programs into the directories you've specified. Remember that any file in those directories is processed as a Windows NT/Windows 2000 CGI file.

Specifying Windows NT/Windows 2000 CGI as a File Type

To specify a file extension for Windows NT/Windows 2000 CGI files, perform the following steps:

  1. From the Server Manager, choose the Server Preferences tab.
  2. Click the MIME Types link.
    3. The Global MIME Types window appears. For more information on the Global MIME Types, see "Choosing MIME Types".
     
  3. Add a new MIME type with the following settings:
  4. Click the New Type button.
  5. Save and apply your changes.

Installing Shell CGI Programs for Windows NT/Windows 2000

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

Overview of Shell CGI Programs for Windows NT/Windows 2000

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

For example, if the server gets a request for a shell CGI file called hello.pl, the server uses the Windows NT/Windows 2000 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 Enterprise Server. For information on setting Windows NT/Windows 2000 file extensions, see your Windows NT/Windows 2000 documentation.

Note  

File associations under Windows have historically been available to the entire system. In Windows 2000, however, file associations have been changed to be user specific. This can affect the Shell-CGI subsystem's ability to execute shell CGIs (.bat, .pl, and so on). See the Microsoft document describing this at:

support.microsoft.com/default.aspx?scid=kb;EN-US;q257592



Specifying a Shell CGI Directory (Windows NT/Windows 2000)

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 Class Manager tab.
  3. Next, choose the Programs tab.
    4. The shell CGI Directory link is highlighted and the CGI window appears.
     
  4. In the URL Prefix field, enter the URL prefix you want to associate with your shell CGI directory.
    5. 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://yourserver[.domain.dom][:port]/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.

    6. Caution  

    The server must have read and execute permissions to this directory. For Windows NT/Windows 2000, 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/Windows 2000. 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/Windows 2000)

You can use the Enterprise 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/Windows 2000.

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/Windows 2000 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.
    4. The Global MIME Types window appears. For more information on the Global MIME Types, see "Choosing MIME Types".
     
  4. Add a new MIME type with these settings:
  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 Enterprise 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.
    3. The Query Handler window appears.
     
  3. Use the Editing Picker to select the resource you want to set with a default query handler.
    4. 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.


Previous      Contents      Index      Next     

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002 Netscape Communications Corporation. All rights reserved.


Last Updated August 02, 2002