In each directory of your data hierarchy you create a file called
index with information about each file you want to serve.
index file might contain the single line:
which when properly processed will grant the server permission to serve
any file in the directory (but not in subdirectories). For more
information about this directive see the section on the
serveall attribute below. A more
index file might look like the following:
Title=This is a descriptive title for file.txt
# This is a comment
Title=This plays some sounds
The file contains four groups of lines called records. The first record
(the single line starting
Owner= in this example)
describes properties of the directory and is called the directory record. It can be empty, but in
general it is a good idea for the directory record to contain an owner
line, like the one above, referring to the maintainer of the directory.
The remainder of this
index file has three file records describing three files,
soundfile, in the directory which we wish to serve. The line
starting with '
#' is a comment. Wherever a '
occurs the remainder of that line is treated as a comment (i.e. ignored).
index file is processed with the utility
wndex (pronounced "windex") to produce a
small database called
index.cache containing information
about this directory and its contents. Detailed information on the
wndex utility is given below, but simply
running it with no arguments in a directory containing an
index file will produce the
for that directory. This file contains all the information in the
index file plus additional information gathered
automatically about the files to be served. In particular the
index.cache file will list the names of the files given in
File= lines of the
index file. Any file on the server whose name is not listed
index.cache file will not be served. This is the
basis of WN security. For security reasons the server will
refuse to use any
index.cache file which is in reality a
symbolic link to another file.
index.cache database has a number of other functions
beyond its security role. Attributes of the files listed in the
index file which can be computed before they are served and
which don't often change are stored in the
For example, the
MIME content type of
is read from the
The other files do not need such a line since
wndex can deduce from the file name
file.txt has type
file2.html has type
text/html. This is
done once at the time
index.cache is created and need not be
done every time the file is served. By the way, if the sound file were
soundfile.au it wouldn't need a
Content-type line either.
The title of a file is another example of information stored in the
index.cache file. With the WN server every file
served has a title (even binaries) and optionally has a list of keywords
associated with it. For an HTML document the title and the keywords are
automatically extracted by
the header of the document and stored in fields of that file's line in
index.cache. These are used for the built-in keyword and
title searches which the server supports.
The files which you wish to serve should be owned by you, or by their
creator, or by whoever is in charge of maintaining them. They should not
be owned by
nobody or whatever user id the server runs under
as set in
This because the
nobody id should have the minimum
permissions possible. It needs to have read access to the files to be
served, but it has no need to be able to write to those files or alter
them in any way.
Thus normally the files served might be owned by the maintainer and have their permissions set to be world readable but writable only by the maintainer (or by no one).
index.cache file which controls access to
everything in a directory should be owned by the maintainer of that
directory and the only permission
nobody should have for
this file is read permission. In fact, for security reasons it the
server was started as
root (and then switched to a safer
refuse to use any
index.cache file which is owned by the
user id (e.g.
nobody) under which the server is running.
This restriction does not apply if
wnsd is run on an
unprivileged port by an ordinary user, because such a user might not be
able to make
index.cache files owned by someone else.
There is one exception to the rule of having nothing owned by
nobody (and that's not a double negative). The exception is
the log files. These files must be writable by the server and it
generally seems sensible to have them owned by the user
nobody under whose identity the server runs. The log file
and the error log file can be specified on the command line when the
server is run or can be set in the
config.h with the
Before describing the
index file in greater detail we
briefly explain the use of the program which reads this file and produces
index.cache database file. Simply running
wndex with no arguments in a directory containing a file
index causes that file to be read and a file called
index.cache to be created in that directory.
There are several command line arguments for
-r option causes
wndex to recursively descend your data hierarchy using all
subdirectories listed in the
Subdirs= line of the
directory record in the
index file (see below).
-c options specify an
alternate name for the
index file and the
index.cache file respectively. For example the command:
wndex -i foo -c bar
will attempt to use
foo as the
index file and
produce the file
bar instead of
-d option specifies
a directory other than the current directory in which to find the
index file and in which to create the
(for quiet) suppresses the printing of any warning or informational
The first group of lines in an
index file provides
information about the directory itself and the collection of files it
contains rather than about any single file in the directory. It is
called the directory record. This beginning collection of lines might
specifies the owner of items in the directory (which is used in the HTTP/1.1 headers sent by the
specifies a "wrapper" for the various searches of the directory. That is
an HTML document which provides a customized response listing the
matching items in one of the various searches of the directory. For more
details see the chapter "Parsed Text and Server Side
Includes on the WN Server" in this guide.
line specifies the name of the file which controls access (by IP address)
to this directory. If this item is omitted then items in the directory
may be served to anyone. For more information on using the access
mechanism see the chapter "Limiting Access to Your
WN Hierarchy" in this guide.
Finally the line starting with
Subdirs= specifies the
subdirectories of this directory which you wish to have recursively
searched when a title or keyword search is done on this directory. More
information about searching can be found in the chapter "Setting Up Searches on the WN Server" in
For a complete list of the possible lines (called "directives") which a directory can have see the section "Directory Directives" in this guide.
After the directory record line group an
index file will
typically have groups of lines called file records describing a
particular file. A file record can be as simple as a single line like
the line "
File=file2.html" in the
example above or it can contain several lines describing the file. For a
complete list of the possible lines (called "directives") which a file
can have see the section "File Directives"
in this guide.
When someone sends a request to your server with only the server name and no file name like:
the WN server automatically translates this to:
adding the file name "
index.html". More generally if a
request is made for a directory, say with the URL
http://host/dir1/dir2/, this will be translated to a request
If you wish the default file name in a particular directory to be
something other than "
index.html" you can use the
directive in the directory record of your
index file to
change it. If you wish to change the default file name for all
directories on the server you can change the
line in the
WN is also able to serve files without explicitly listing them
index.cache file. This is done
by putting the line:
in the directory record of the
index file for a directory or
wndex with the
-a option. Either of these
specify that any file in this directory, which does not start with the
.', or contain a '
~', may be served,
not just those listed in the
index file. The files
index.cache will also not be served.
(Indeed if the
is used with
wndex there need not even
index file, because an
will be created just as if the
directive had been used.)
Note: When this directive is used in a directory protected by an
accessfileor a password file be sure that these files have names that start with '
.', or contain a '
~'. Or better, put these files in a different directory from which nothing is served.
directive is used the server will attempt to set the content type
correctly based on the file name suffix using the same default
correspondences between type and suffix that
wndex uses. Indeed when
wndex is run on a directory with the
directive, it behaves as if all files in the directory (except those
starting with '
.' or containing a '
listed with a
directive. If the
line (and the corresponding entry it creates in the
index.cache file) are not present then only the files
explicitly listed with a
File= directive will be
The default correspondences between file name suffixes and MIME types are
specified in the "
mime.types" file. A default version of
the file is in
file should be installed in a known location. The default location is in
src hierarchy, but this can be changed by
specifying a different value when the
is run or by editing the value of
mime.types file exists so that you can add to it if you wish
to add new kinds of documents to your server. The format of the file is
explained in the file. If this file cannot be opened then
wndex will use compiled in defaults which
are the same as what is currently in the default version of this file.
mime.types file is read whenever
wndex is run so
wndex always knows the latest additions.
This file is also read by
wnsd (but not
startup for use with directories with the
wnsd stand-alone server reads this file when
it is started or restarted, but only takes note of new suffixes and their
MIME types. You cannot change the MIME type corresponding to one of the
standard suffixes (as listed in the default
file). To do that you need to change the server source and recompile.
It is fine to have file records in an
index file which also
directive. In this case the file directives take precedence. Thus if
you had an
index file consisting of:
the server would consult the file record for "
first and see that it is of type
would be silly to actually do this, of course) and use that type. But
another file "
bar.html" in the directory would also be
served with the type indicated by its suffix. Files with no file record
index file and no recognized suffix will be given the
default content type which can set with the
wndex is run on an
index file with the
directive all the files currently in that directory which can be served
are given entries in the
index.cache file. Title and keyword searches only see files listed in
index.cache file. Likewise context and grep searches only seek matches in files
listed in the
index.cache file. Thus if a file is added to
a directory with the
directive it will not be visible to searches unless
wndex is re-run in that directory. If it
has not been re-run the file will still be served, however. Still, it is
good practice to re-run
time you add or delete a file in a directory with the
directive. (Of course, it is required to do this for a directory without
directive.) There is no need to re-run
wndex if you only change an existing file,
unless you change its title or keywords.
There is no way to use wrappers or includes for
files not listed in the
index file. So generally, the few
seconds it takes to add a document's name and a descriptive title to your
index file and then to run
wndex will pay off.
If you do not wish the
directive to be allowed on your server you can disable it by uncommenting
line in the
This does not affect the ability of
wndex to write
entries for all files in a directory with the
directive. But it means the server will only serve files listed an
There are three situations when the client request will be denied but for which you can supply customized error messages. These are requests for non-existent files, requests for files which require a password but for which no valid password was given, and requests from an invalid host for files limited to certain hosts. The lines:
in a directory record of an
file specify URL's to which clients are redirected when a non-existent
file is requested and when a document protected by an access control file is requested from an
invalid host. The last line specifies a file to be sent when a password
protected file is requested without a password or with an invalid
password. For technical reasons it wouldn't work to have this be a
In the first two lines above (specifying redirection) the URL's given can be relative URL's, so the lines:
are valid. Default values for these three directives may be specified by
and recompiling the server. More information on customized error
messages can be found in section "Directory
Directives" in this guide.