NSAPI module

NSAPI support

Overview
The NSAPI module can load and run NSAPI-compatible applications.

NSAPI, Netscape's web server API, provides a programmer's interface to the core operations of a web server. NSAPI applications can access and modify the internal state of a web server, and may contribute to processing a user's request, authenticating it, locating resources, generating content and logging any results.

The Zeus NSAPI module provides a binary-compatible emulation of Netscape's NSAPI interface v3.0 and v4.0. Zeus does not provide any support for NSAPI application development.

Configuration
NSAPI configuration is held mainly in an 'obj.conf' file. In addition, if your web server runs as the root user, you can configure an alternative user and group that the NSAPI execution environment will use.

Three Netscape-like configuration files are required: 'obj.conf', 'mime.types' and 'magnus.conf'. These three files must be stored in a https-<vserver name>/config directory, by default $ZEUSHOME/ns-config/https-<vserver name>/config.

You can install default configuration files from the NSAPI module configuration page on your Zeus admin server.

Sample obj.conf file
# Sample obj.conf file
#
# $ZEUSHOME/ns-config/https-foo/config/obj.conf
Lines beginning '#' are comments and are ignored


Init fn="load-modules" funcs="myauth"
     shlib="/usr/local/nsapi/libs/auth.so"
     
Init fn="load-modules" 
     funcs="myrewrite, mylog, mylog-open"
     shlib="/usr/local/nsapi/libs/util.so"

Init fn="mylog-open" 
     logfile=/usr/local/auth/access.log

 
Init commands are run at startup. The first two commands import the function 'myauth' from the shared library 'auth.so', and 'myrewrite', 'mylog' and 'mylog-open' from 'util.so'.

The third command runs the function 'mylog-open' once at startup.


 
<Object name="default">
AuthTrans fn=basic-auth auth-type="basic"
          userdb="/usr/local/auth/users.dat" userfn=myauth 
      
NameTrans fn=myrewrite from=/somewhere/
          to=http://www.somewhere.else.com/
</Object>

<Object ppath="*/secure*">
PathCheck fn=require-auth realm="Secure Site"
          auth-type="basic" auth-user="(pete|joe|karen)" AddLog
          fn=mylog
</Object>
 
The first word of a command indicates the stage in the web server's processing where the command should be executed.

All commands, other than Init commands, are grouped into 'objects'.

Commands in the 'default' object are run on every request. Additional 'objects' can be used to augment the default object. The easiest way to specify additional objects is to give them a ppath regexp which matches a full filesystem name.
Commands are one line long, but any line beginning with whitespace (space or tab) is taken to be a continuation of the previous line.
This sample obj.conf supposes the user has created or acquired NSAPI libraries auth.so and utils.so containing the appropriate functions.

Sample mime.types file
# Supplementary mime types for NSAPI
#
# $ZEUSHOME/ns-config/https-foo/config/mime.types
Lines beginning '#' are comments and are ignored


type=image/gif  exts=gif
type=text/html  exts=log,dat
These mime types override the Zeus Mime-Typer


Sample magnus.conf file
# Default Zeus magnus.conf
#
# $ZEUSHOME/ns-config/https-foo/config/magnus.conf

LoadObjects obj.conf
'LoadObjects' provides the name of the obj.conf file. All other tags in this file are ignored.

More Information
A typical NSAPI installation procedure for a Virtual Server would proceed as follows:

  1. Enable the NSAPI module, then configure it as follows:
    1. Select a location for the configuration files
    2. Select a sandbox user and group (optional)
    3. Commit these changes by clicking the 'update' button
  2. Copy the skeleton config files by returning to the NSAPI configuration page, and clicking the 'Create Configuration' button at the bottom of the page. This will copy skeleton a obj.conf, mime.types and magnus.conf file to your config directory.
  3. Run the install script for your NSAPI application. You will be probably be asked to provide either the location of your obj.conf file, or your configuration root.
  4. Restart your Virtual Server (traffic lights!)

You can find more information on how to configure and develop NSAPI applications at developer.netscape.com

It is relatively easy to debug or trace NSAPI applications.

Tuning Your NSAPI installation
NSAPI applications are run in an external, multithreaded runner called 'zeus.nsapi'. There is one instance of this runner for each Virtual Server that uses the NSAPI module.

The runner maintains a pool of threads to service NSAPI requests. You can tune the maximum size of this pool, and the backlog of pending requests using tuning parameters in the global.cfg file:

tuning!modules!nsapi!maxthreads   Maximum number of concurrent threads (default 128)
tuning!modules!nsapi!maxqsize   Maximum backlog of requests (default 512)
These values should be adequate for a wide range of systems.

You can also tune the maximum stacksize that each thread is allocated:

tuning!modules!nsapi!stacksize   Thread stacksize (bytes)
The default value for this parameter is determined by your operating system configurables.

The global.cfg file is located in $ZEUSHOME/web.