An arbitrary "filter" can be assigned to any file to be served. A filter
is a program which reads the file and has the program output served
rather than the content of the file. One common use of this feature is
for on-the-fly decompression. For, example a file can be stored in its
compressed form and assigned a filter like the UNIX
utility which uncompresses it. Then the client is served the
uncompressed file but only the compressed version is stored on disk. As
another example, you might use "
nroff -man" as a filter to
utility for formatting man pages before serving. There are many other
interesting uses of filters. Be creative!
A filter is assigned to a file by use of the "
Filter=" directive in the
file's record in its
index.cache file. For example, the
cause the compressed file
foo.gz to be uncompressed on the
fly and served to the client as a
Notice that it is necessary to have the content-encoding line to override
the default action of
wndex which is to infer
from the "
.gz" suffix that the content-encoding is
x-gzip. If the compressed file were named simply
foo" then the content-encoding line would be unnecessary.
directive takes the value of a path to a file in three different forms.
If the path begins with a '
/' then it is relative to the
system root. If it begins with '
~/' then it is relative to
the WN hierarchy root, and otherwise it is relative to the
directory containing the
If a file has a filter only that file will be filtered, not any wrappers or includes.
The ability to filter files can be restricted in several ways. If
WN is invoked with the
-e option then no includes,
filters, or CGI/1.1
programs will be executed.
-E option in
conjunction with the
-T option restricts
the use of filters to those listed in
owned by trusted users or groups. The
-u option allows only the
use of filters owned by the owner of the
which lists them.
The directory directive:
specifies that files in this directory should all be treated as if the
directive had been set to
/path2/filter. To override this
setting and specify no filter use the "
The filter mechanism built into WN has most of the functionality of the Common Gateway Interface (CGI) standard and has some features CGI/1.1 does not. Filters are also in some ways more secure. This makes them a good choice for applications where compatibility with the CGI/1.1 standard is not required.
The first thing to note is that there is no requirement that the filter program actually make use of the file being filtered. This file must exist though.
Thus if an empty file "
foo" is created and has an
index file entry like:
then the output of the program "
someprogram" will be served.
A program used in this way differs somewhat from a CGI/1.1 program in that no
headers should be supplied by the program as WN will
automatically provide them. For example, while a CGI/1.1 program typically
starts with printing "
Content-type: text/html" followed by a
blank line, this should not be done for "
someprogram" in the
index entry above, because WN will automatically
provide the appropriate HTTP/1.1 headers based on the
line in the
An important difference between filters and CGI/1.1 programs is that the
output of filters can be parsed while CGI/1.1 output cannot. The
fact that you want the output parsed must be signalled by the use of an
line in the directory's
If you wish to have all the standard CGI/1.1 environment variables made available to the filter program you can do so by adding the line:
to the file record. A list of these environment variables can be found
in appendix "CGI and other Environment Variables
for the WN Server" in this guide. Also see the sample CGI program which is located in the
/docs/examples/sample.cgi which accompanies the
One difference between CGI/1.1 programs and filters
is that with filters there is no way to have a non-empty
environment variable since anything appended to the path part of the URL
will be interpreted as a path to an actual file. Of course the "query"
part of a URL (everything after a '
?') will work for filters
as well as CGI/1.1
programs and its contents will be put in the
Another difference between CGI/1.1 and filter programs
is in the handling of
PUT data. A CGI/1.1 program reads the
data provided by the client on its UNIX
stream. This is not possible for a filter since its
is attached to the file it is supposedly filtering. To use the
POST method with a filtered file, the
directive must be used since otherwise the server will not permit a
PUT. It is then possible to read the
POSTed data by opening and reading the temporary file
containing this data. The name of this file changes with each request,
but if "
used then the name is given in the WN specific CGI environment
depending on the method used to submit the data.
One advantage of using a filter instead of a CGI/1.1 program is that it
may have slightly better security. With a filter the name of the
executed program is never visible outside the server. It is not in any
URL and it is not in any served file. Perhaps a more important feature
is that no arguments can be supplied to a filter except those listed in
index file filter
entry. Unlike CGI/1.1
programs, it is not possible for a remote user to supply any arguments
whatsoever to the program.