WN home page

Version 2.5.0
[Previous] [Next] [Up] [Top] [Search] [Index]

WN Auxiliary Modules


WN provides some features by auxiliary modules. These are separate C programs called by the server to provide some function like authorization (authentication) or indexed searches or database access. The current release of WN has a module for authorization using the HTTP/1.1 Basic Authentication scheme supported by most clients and future releases will have a module to do index searches.

The current version also has the support infrastructure or "hooks" for several services which maintainers may wish to create.

14.1 Database Modules

The index.cache in each directory is in fact a small flat database containing characteristics of that directory and the files contained in it. This can be replaced on a per directory basis by a user supplied module to provide the same information. In the index.wn file for such a directory you should create a directory directive entry like:

Cache-Module=/full/path/to/foo

The program "foo" should be an interface to your database. It is permissible to follow "foo" in this line with any desired arguments to be passed to it. The program "foo" should read the environment variable WN_KEY which will contain everything after the final '/' in the URL being served. Based on this key it should return a single line in the format of an index.cache file. Any "File=" directives in an index.wn file which contains a "Cache-Module=" directive will be ignored.

You may wish the cache module function to have access to more information about the request. If you put the directive "Default-attributes=cgi" before the "Cache-Module=" directive then all the CGI environment variables will be set.

If the file cache module encounters an error, such as no entry corresponding to the supplied key, it should return nothing and exit with a negative status. This signals the server to return an appropriate error message.

14.2 File Modules

It is perhaps more useful to have the files being returned reside in a database. To use such a database interface called "bar", in the index.wn file for its directory you should create a directory directive entry like:

File-Module=/full/path/to/bar

The program "bar" should be an interface to your database. It should read the environment variable WN_KEY which will contain everything after the final '/' in the URL being served. Based on this key it should return a document to be served (perhaps after processing with wrappers or includes). When a file module is used it is also necessary to either use a "Cache-Module=" or have an actual index.cache file with the name of all documents which might be returned by the database or to have an index.cache file created from an index.wn file containing the directory directive "Attributes=serveall". If the file module encounters an error, such as no document corresponding to the supplied key, it should return an appropriate error message of the same content-type as the requested document.

As with cache modules, you may wish the file module function to have access to more information about the request. If you put the directive "Default-attributes=cgi" before the "File-Module=" directive in your index.wn file then all the CGI environment variables will be set.

14.3 Authorization Modules

Authorization requests in WN are normally handled by an authorization module. The current release contains a Basic Authentication module and a prototype implementation of Digest Authentication, but users are invited to provide their own.

Warning: I would strongly advise against using basic authentication described here to protect sensitive information on a server which runs on system on which untrusted users have accounts.

The contents the Authorization: request header is passed to the module on the UNIX stdin(3) stream (as of version 1.10).

The server expects this module to exit with a status indicating that access is granted, denied, or that an error occurred. Anyone writing an authorization module should consult the file /wnauth/wnauth.h. The "#defines" listed there specify the error status to use for granting, denying or indicating certain errors.

To use a user supplied authorization module named authmod the index.wn file of each directory requiring authorization should contain lines like:

Authorization-realm=myrealm
Authorization-module=/full/path/to/authmod
Authorization-type=basic

The program authmod should indicate the granting or denial of authorization by its exit status as described above. The "Authorization-realm=" is a designation which is sent to the client with the authorization request allowing the client to decide whether the user has already supplied a password which can be reused (if the realm is the same as when the password was supplied) or if a new password needs to be entered.

14.4 Index Search Modules

Indexed searches can be supported in WN by auxiliary modules. Two such modules are provided as examples and maintainers may wish to create others. To use such a module you should have an HTML <form> action be something like:

http://host/dir/search=index

Then in the index.wn file in the directory record you should have a line like:

Search-Module=/full/path/to/searchmod

The program searchmod should read the CGI environment variable QUERY_STRING and return a partial HTML document. The typical case would be the program returns an unordered list of anchors to documents containing a match to the query string. This list can be wrapped by including a "Searchwrapper=" directory directive. If it is not, a default wrapper with text like "Here are the matches for your search." is supplied.

Two simple examples of a search-module (written in perl) are included in the distribution in the files bin/wnseven_m and bin/wnsectsearch.


WN version 2.5.0
Copyright © 1998-2005 John Franks <john@math.northwestern.edu>
licensed under the GNU Free Documentation License
Last modified: Sat June 18 2005
[Previous] [Next] [Up] [Top] [Search] [Index]