Extending your server with programs


n addition to serving HTML documents, your server can run programs that interact with clients. These applications that run on the server computer are called server-side applications. (Client-side applications, which are downloaded to the client, run on the client machine.)

Your server can run these types of server-side applications:

This chapter describes how to install Java applets, CGI programs, and JavaScript applications onto your server. Plug-ins extend or replace your server's features. For example, you can use plug-ins to provide a different way to control access, or different logging mechanisms.

For information on writing and installing plug-ins, see the DevEdge site at http://developer.netscape.com/library/documentation/.

Additionally, your server can send these types of client-side applications to clients:

This chapter deals mainly with the installation and configuration of server-side programs, although you'll find some information on client-side applications as well. For more detailed programming information, see the Netscape's DevEdge online documentation web site at
http://developer.netscape.com/library/documentation/.

Additionally, this chapter describes the steps for specifying a default query handler CGI program. (A query handler processes text sent to it via the ISINDEX tag in an HTML file.)

Installing server-side programs

Java applets, JavaScript applications, and CGI programs have different strengths and uses. Java 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; what makes them all CGI programs is the standard way they pass information between clients and servers. JavaScript applications are written in JavaScript, an object-based scripting language; it is easier to learn than an object-oriented programing language and lends itself to rapid application development.

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.

Installing server-side Java applets

Java is a programming language designed for platform-independent application development. If you have a server-side Java applet that works on a Unix server, you can also use it with a server running on Windows NT. Like a CGI program, a server-side Java applet is triggered by a client sending or requesting information from a URL. However, server-side Java applets and client-side Java applets have different formats and are not interchangeable.

To use server-side Java applets with your server, you must enable your server's Java interpreter and copy all Java applets into a specified directory. All server-side Java applet files must be named in the standard format name.class. For more information on creating Java applets that work with your server, refer to Netscape's DevEdge online documentation web site at
http://developer.netscape.com/library/documentation/.

To enable your server to use server-side Java applets:

  1. From the Server Manager, choose Programs|Java. The Java form appears.
  2. Click the Yes button to enable the Java interpreter.
  3. Specify a Java applet directory by typing it in the Java applet directory field.
  4. Click the OK button.
  5. Save and apply your changes.

Be sure to copy all server-side Java applets into the directory you've specified.

Installing CGI programs

Common Gateway Interface, or CGI, programs can be created with any number of programming languages. On a Unix machine, you're likely to find CGI programs written as Bourne shell or Perl scripts. On a Windows computer, you might find CGI programs written in C++ or batch files.

Regardless of the programming language, all CGI programs accept and return data in the same manner, as described in Netscape's DevEdge online documentation web site at
http://developer.netscape.com/library/documentation/.

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

There are benefits to either implementation. If you want only a specific set of users to be able 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 will attempt to interpret any file you place in that directory as a CGI program. By the same token, if you choose the file type option, your server will attempt 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.

Specifying a CGI directory

To specify a CGI-only directory:

  1. From the Server Manager, choose Programs|CGI Directory. The CGI Directory form appears.
  2. In the URL Prefix field, type the URL prefix you want 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.

  1. 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.
  2. Click OK.
  3. 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--any files in those directories will be processed as a CGI file, so you don't want to put HTML files in your CGI directory.

Specifying CGI as a file type

To specify CGI programs as a file type:

  1. From the Server Manager, choose Programs|CGI File Type. The CGI as a File Type form appears.
  2. From the Resource Picker, choose the resource you want this change to apply to.
  3. Click the Yes radio button.
  4. Click OK.
  5. Save and apply your changes.

The CGI files must have the file extensions .bat, .exe, or .cgi. Any non-CGI files with those extensions will be processed by your server as CGI files, causing errors.

Downloading executable files

If you're using .exe as a CGI file type, users will not be able to 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 Server Preferences|MIME Types. 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.

Using the query handler

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, do the following:

  1. Choose Programs|Query Handler.
  2. 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.
  3. 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.
  4. Click OK.
  5. Save and apply your changes.

Enabling WAI services

Web Application Interface (WAI) services are a kind of plug-in that uses the Common Object Request Broker Architecture (CORBA).

Before you use WAI services, you must enable them on your server. Enabling WAI services essentially turns on Internet Inter-ORB Protocol (IIOP) support in the server. You may have other (non-WAI) applications that need this support. If you need IIOP support, enable WAI services.

To enable WAI services on your server:

  1. From the Server Manager, choose Programs|WAI Management.
  2. The WAI Administration page appears. To enable WAI services, click the Yes radio button.
  3. Save and apply your changes.

For more information about WAI, see Writing Web Applications with WAI on Netscape's DevEdge online documentation web site at
http://developer.netscape.com/library/documentation/.

Installing server-side JavaScript programs

To install server-side JavaScript programs, you need to activate server-side JavaScript for your server and use the Application Manager. This section includes information on accessing and using the Application Manager to install server-side JavaScript applications, as well as perform other functions.

For more information about writing JavaScript applications, see Writing Server-Side JavaScript Applications on Netscape's DevEdge online documentation web site at http://developer.netscape.com/library/documentation/.

Activating server-side JavaScript

If you are using server-side JavaScript applications, you must first activate server-side JavaScript for your server.

To enable server-side JavaScript:

  1. From the Server Manager, choose Programs|Server Side JavaScript.
  2. Choose Yes under "Activate the Server Side JavaScript application environment."
  3. If you want to require the administration server username and password before allowing access to the Application Manager, choose Yes. For more information, see "Securing the Application Manager" on page 152.
  4. Click OK.
  5. Save and apply your changes.

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:

Running the Application Manager

To run the Application Manager from the Server Manager, choose Programs| Server Side JavaScript and click the link to the Application Manager. You can also run the Application Manager by loading the following URL in Navigator: http://server.domain/appmgr.

You see the following screen.

The Application Manager

The Application Manager displays all applications currently installed on the server in a scrolling list in the left frame. Select an application by clicking its name in the scrolling list.

For the selected application, the right frame displays

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.

Click Configure to configure the default settings for Application Manager. Click Add Application to add/install a new JavaScript application. Click Documentation for further documentation on server-side JavaScript. Click Help for instructions on using Application Manager.

Securing the Application Manager

Warning!
Your Application Manager runs on your web server (rather than on the administration server). The Application Manager is installed into the js/ appmgr directory. You can access it without the Server Manager with this URL: http://yourserver.domain.com/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 user and password for access to the Application Manager, follow these steps:

  1. From the Server Manager, choose Programs|Server Side JavaScript.
  2. Under "Require administration server password for Server Side JavaScript Application Manager" choose the Yes radio button.
  3. Save and apply your changes.

You then must enter the administration server username and password to use the Application Manager.

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 of 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:

  1. From the Server Manager, choose Programs|Server Side JavaScript.
  2. Click the link to the Application Manager.
  3. Click Add Application from the top of the page. The Add Application page appears.
  4. 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/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" on page 154.
  5. In the Web File Path field, type the absolute path to the .web file for the application. This is a required field.
  6. 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.
  7. In the Initial 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.
  8. 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.
  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. This can be client cookie, client URL, server IP, server cookie, or server URL.
  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 from 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/appName/page.html.

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

For example, if your server is named myserver and your domain name is mozilla.com, the application URL for the Hello World sample application is http://myserver.mozilla.com/world/hello.html.

When a client requests this URL, the server generates HTML for the specified page in the application and sends it 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" on page 68. For more information on restricting access to part of your server, see "Controlling access to your server" on page 97.

Modifying installation parameters

To modify an application's installation parameters, 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, 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, click Start. If the application starts successfully, clients can run the application.

To stop an active application, click Stop. The application's status changes to "stopped," and clients can no longer run 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. For any changes you have made to 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/appmgr/control.html?name=appName&cmd=action
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:

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

Click Configure to configure default parameter settings for the Application Manager. When you install a new application, the default installation parameters are used for the initial settings.

You can specify the following default settings:

Installing client-side programs

Installing client-side programs in your server is relatively easy. There are two types of client-side programs: Java applets and JavaScript programs. Client-side Java applets are executable files identified in an HTML document, retrieved from the server, and executed on the client. The applets can reside anywhere under your server's primary document root. Client-side JavaScript programs are embedded in HTML files and executed on the client.

Installing client-side Java applets

Instructions for creating client-side Java applets are outside the scope of this book. After you've created an applet, to install it you must copy it into a directory from which your server can deliver it. To send it to a client, it must be referenced in an HTML file.

Installing client-side JavaScript programs

Client-side JavaScript programs are created by lines of JavaScript code embedded in HTML files. The HTML files travel from the server to the client. Once the files reach the client, Navigator interprets the JavaScript code and performs the specified actions.

With LiveConnect you can connect server-side Java and JavaScript applications, or client-side Java and JavaScript applications. For more information on LiveConnect, on embedding JavaScript in HTML, and on using client-side JavaScript with other programs, refer to the documentation on the DevEdge online documentation web site at
http://developer.netscape.com/library/documentation/.


Copyright 1997 Netscape Communications Corporation. All rights reserved.