(this chapter contributed by Doug Hardie)
This document is for the system "webmaster". It addresses an approach to management of the Cache files that may be useful in some special situations. Normally WN will not serve a file from a directory unless there is a Cache file in that directory that authorizes the serving of that file. Default Cache Files provides an alternative approach to Cache files for those situations where maintaining the Cache file in a specific directory is not viable.
The use of Default Cache files requires the administrator to carefully design and control the web space as it is possible to create situations where the security and protection mechanisms can be bypassed through the incorrect use of Default Cache files. Most WN installations do not need, and should not have, Default Cache files enabled.
The most obvious example of a situation where Default Cache files are useful is to serve data from read-only media such as a CD ROM where it is impossible to create cache files in each directory from which you wish to serve documents.
Another example environment where Default Cache files may be useful is in a situation where there are individual user web pages. In this case it may not be reasonable to expect the individual users to create and properly maintain the Cache files. In this situation you might want to create a default cache file for all user web pages.
However, there are some potential pitfalls with this approach. If the user web pages are only available to the users through ftp, then you can properly control the situation. If the users can login to the web server you may have problems with users establishing links to directories/files outside the web space. For instance, a user could establish a link to the system password file and it would then be served. It is probably not a good idea to use Default Cache files if the users have the ability to establish links. The same probably applies for executable programs or cgi's.
Another example would be for a server that has a large web space for which everything in that space is to be served. While this can be handled by using a Cache file with serveall in every directory, that may be tedious to setup and maintain. A Default Cache file for that web space will provide the same effect.
Again, the administrator has to be careful to ensure that there are no unexpected links or cgi's.
If you believe you have a use for Default Cache files, then you will need to rebuild the WN server to include the DEFAULT_CACHEFILE_LIST option as described below.
To configure WN for Default Cache files, you must
first decide where you are going to put a cache file list that
contains the listing of the Default Cache files to be used.
For the examples used in this document, the cache file list is
in /www/bin/cachefilelist.
Then you must edit config.h and change USE_DEF_CACHE_LIST to
TRUE. The default is FALSE.
#define USE_DEF_CACHE_LIST (TRUE)
Then you must set the macro USE_DEF_CACHE_LIST to
the complete system path to a file containing the list of
default cache files. In this example the command would look
like:
#define DEFAULT_CACHEFILE_LIST "/www/bin/cachefilelist"
Then you need to create the default cache files. They are best
created by creating an index file as described previously and
using wndex to create the cache file. You may want to have
several different default cache files for separate portions of
the web space. Once the default cache files are established,
enter them into the cache file list. For example, two default
cache files are desired: /www/bin/cache/users and
/www/bin/cache/web. Create these files using wndex
and then create /www/bin/cachefilelist using the following
format:
# Default cache file for public web pages
/www/docs/pub/* /www/bin/cache/web
# Default cache file for user home pages
/usr/home/*/public_html/* /www/bin/cache/users
# Default cache file for a single directory
/www/test /www/bin/cache/single
# Default cache file for user home pages in sub directories
/usr/home/??/* /www/bin/cache/users
The first entry on each line is a directory in the web space which, will use a default cache file. The second entry on the line is the path to the cache file you want to use. This cache file must be in a directory in the WN data hierarchy. Comments in this file are anything on a line after the first '#'. The first entry may contain the wildcards '*' and '?' which behave in the same way they do as shell metacharacters.
In the first entry of the example above the web pages in
/www/docs/pub and its subdirectories will use the
web default cache page. For the second entry,
anything in public_html directory inside a user home directory
(e.g. /usr/home/bob/public_html/whatever.html)
will use the web default cache page. All other
pages must have a cache file in the directory of the requested
page. In the third entry, only files in /www/test will use the
default cache file. Subdirectories must have their own cache
files. The fourth entry shows how a large number of home pages
could be split into multiple directories - each having two
characters in their names (e.g., 00 - 99). Other directories
in /usr/home will not use the default cache file.
Note, all the default cache files and the cache file list must be owned and have the same permissions as a normal cache file. If a cache file exists in a directory it will always be used in place of the default.
It is possible for a directory to use a default cache file and a subdirectory to use a real cache file. If a directory matches more than one item in the cache file list the first matching entry will be used.
The default cache file can contain any WN cache file directive. However, in general the serveall directive will be necessary. While directives for specific files can be included, that is probably not a good approach since those files only exist in one directory. You should use a cache file in the directory for those situations. Other directives such as the default content may be helpful.
Once the WN server is running with Default Cache files, you may need to make changes. The Default Cache files themselves can be updated just like normal cache files. Likewise changes to the cache file list can be made while the server is operational. You do not need to restart the WN server for changes to either.