Index File Directives for the WN Server

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

Index File Directives for the WN Server

This is a list of the items which may be placed in an index.wn file to be processed by wndex. This file consists of a collection of records each of which consists of a group of lines pertaining to single file. Each line of a record begins with a directive like "Title=" which indicates that the remainder of that line is to be take as the title of the document whose record contains this line. The "File=" directive is special in that it indicates the beginning of a new record. The value of the "File=" directive is the name of the file whose record will follow. Letter case is not significant in directive keywords.

When the character '#' is encountered in an index.wn file it is assumed to be the start of a comment and everything after it on that line is ignored. To include the '#' character in, for example, a document title, it must be escaped with the '\' character. That is. when "\#" is encountered it does not signify a comment and the character '#' (without the backslash) is treated as a normal character. In fact, since all directives contain the character '=', all lines which do not contain this character are silently ignored. Also a single conceptual line of an index.wn file can be spread over several actual lines by ending all but the last line with the '\' character. That is, if a line ends with '\' that character is removed and the contents of the next line is considered a continuation of the current line. The maximum allowed length of a line (including continuation) is 1024 characters. The maximum allowed length of all the records corresponding to one document is 8192 characters.

The first record in an index.wn file is special and is intended to describe attributes of the entire directory rather than individual files. It contains lines with directives specifying attributes of the directory as a whole or all the files in it. The next section is a complete list of these directory directives.

B.1 Directory Directives

Accessfile -- Specify directory access control file.

The line:

Accessfile=/dir/accessfile

specifies that the file /dir/accessfile is to be used to determine access privileges (by hostname or IP address) for this directory. If this line is omitted access is allowed for everyone. Both the path /dir/accessfile and the path ~/dir/accessfile are taken relative to the WN root directory. In particular the accessfile must be in the WN hierarchy (unlike includes or filters, for example.) If the path does not begin with a '/' or a '~' then it is relative to the directory containing the index.wn file. See the chapter "Limiting Access to Your WN Hierarchy" in this guide.

Access-denied-URL -- Set URL for requests for which access is denied.

The line:

Access-denied-URL=http://host/dir/foo.html

or the line:

Access-denied-URL=/dir/foo.html

specifies that any request for a document in this directory which is denied because of an "Accessfile=" restriction should be redirected to the given URL. A default value for all directories can be set by uncommenting the "#define ACCESS_DENIED_URL" line in config.h and recompiling. If you use this directive be sure that the file foo.html does not have restricted access or you can create an infinite loop. This line has the special feature that it can also be placed as the first line of the "Accessfile=" controlling the directory. A line in the accessfile will override any value set in the index.wn file.

Attributes -- Set directory attributes.

Currently there are only two directory attributes, viz. "nosearch" and "serveall". Letter case is not significant in the attribute value.

Attributes=serveall: Specifies that any file, with a few exceptions, in this directory may be served not just those listed in the index.wn file. 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. The exceptions are that files whose name starts with '.' or ends with '~' as well as the files "index.wn" and "index.cache" will not be served.

Note: When this directive is used in a directory protected by an "Accessfile=" or 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.
Attributes=nosearch: Specifies that the index.cache databases in the current directory and its subdirectories should not be searched when the server does a title, keyword or user supplied field search. Likewise context and grep searches will not be allowed in this directory. In this case when an attempt is made to do so an error message is returned to the client. It is also possible to exclude only some files from searching with the "Attributes=" file directive.

Authorization-Module, Authorization-Realm, Authorization-Type -- Specify authorization module.

Currently WN includes a "basic" authorization module called wnauth. Its use is described in the chapter "Limiting Access to Your WN Hierarchy". Alternatively you can make your own module to handle authorization. Data is passed via standard input to this module. More specifically such a module should expect to read Basic user:password on standard input for Basic authentication, where "user" is the client supplied user name and "password" the client supplied password. The WN server expects this module to exit with status 0 if authorization is granted and with status 1 if access is denied. See the source of wnauth in /wnauth/wnauth.c for a detailed example.

For security reasons when you use an "Authorization-Module=" you are required to use either the -t or -T options or the -a or -A options and to have the index.cache file in the protected directory owned by the trusted user or group. This is to guard against counterfeit authorization modules.

Auth-denied-file -- Specify the name of an HTML file to be used as the error message when an authentication attempt for a password protected directory fails.

The line:

Auth-denied-file=~/dir/foo.html

specifies that any request for a document in this directory which is denied because of an authorization module restriction results in the file ~/dir/foo.html being sent instead. A default value for all directories can be set by uncommenting the "#define AUTH_DENIED_FILE" line in config.h and recompiling. Note that this is not a URL but the name of a file whose content is to be sent as error text when authentication is denied. If the file name starts with '~/' as above it is assumed to be relative to the WN root directory. Otherwise it is assumed to be a path relative to the directory containing the index.wn file.

Cache-Module -- Specify program to be used as interface to database for index.cache entries.

If this line specifies a program then instead of looking for file entries in the index.cache file this program is executed after putting the base name of the URL in the environment variable WN_KEY. This provides a mechanism to use a real database rather than the file index.cache. Note that the directory directives are still obtained from index.cache. The output of this module must be in the format of an index.cache line. Title, keyword and grep are not supported since that would require reading the entire database.

Default-Attributes -- Specify the default value of file attributes directive for every file served from this directory. This directive should not be confused with the directory attributes directive.

The line:

Default-Attributes=parse,dynamic

specifies that files in this directory should be parsed and marked as dynamic documents unless they have an attributes directive specifying the contrary.

Default-CGI-Handler -- Specify a default value for the "CGI-Handler=" file directive.

The line:

Default-CGI-Handler=/dir/handler

specifies that files in this directory should all be treated as if the "CGI-Handler=" file directive had been set to /dir/handler. To override this setting and specify no CGI handler use the "CGI-Handler=<none>" directive.

Default-Charset -- Specify the default character set to be added to the MIME type for documents with content type text/*.

The line:

Default-Charset=iso-8859-1

specifies that documents in this directory which have a MIME type of text/* should have a character set parameter with this value appended. E.g. a document of type text/html will be sent with a content type header

Content-type: text/html; charset=iso-8859-1

The default value for this is iso-8859-1.

Default-Content -- Specify the default MIME content type for items in this directory.

The line:

Default-content=text/html

specifies that files in this directory which do not end in a suffix recognizable to wndex should be given the type "text/html". Any legitimate MIME type may be used as the value.

Default-Cookie -- Specify the default cookie or cookie generating script for items in this directory.

The line

Default-Cookie=name=value

or the line

Default-Cookie=!my_cookie_script

specify that files in this directory with no Set-Cookie directive should be treated as if they had such a directive with the value name=value or !my_cookie_script.

Default-Document -- Specify the default document for this directory.

The line:

Default-Document=foo.html

specifies that a URL pointing to this directory like http://host/dir/ will result in serving the document wnroot/dir/foo.html instead of wnroot/dir/index.html. Uses of this include making the default document a CGI program with "Default-Document=foo.cgi" or having a directory with HTML files all ending with the suffix ".htm" and using the directive "Default-Document=foo.htm". This directive applies only to the directory containing the index.wn file, not to any subdirectories.

Default-Filter -- Specify a default value for the "Filter=" file directive.

The line:

Default-Filter=/path2/filter

specifies that files in this directory should all be treated as if the "Filter=" file directive had been set to /path2/filter. To override this setting and specify no filter use the "Filter=<none>" file directive.

Default-Includes -- Specify a default value for the "Includes=" file directive.

The line:

Default-Includes=footer.html

specifies that this line should be used as the "Includes=" directive for any document in this directory which does not have an "Includes=" directive explicitly set. To override this default value simply specify an explicit "Includes=" directive or use "Includes=<none>" to have none.

Default-List-Includes -- Specify a default value for the "List-Includes=" file directive.

The line:

Default-List-Includes=header.html,footer.html,disclaimer.html

specifies that this line should be used as the "List-Includes=" directive for any document in this directory which does not have an "Includes=", "Wrappers=", or "List-Includes=" directive explicitly set. To override this default value simply specify an explicit "List-Includes=" directive or use "List-Includes=<none>" to have none. Note that the example above grants permission for the inclusion of the three files listed. It does not require their insertion. However, it does cause all files in the current directory to be parsed for includes unless this "Attributes=" is overridden.

Default-Max-Age -- Specify the default value for the "Max-Age=" file directive.

The line:

Default-Max-Age=2 weeks

specifies the Cache-Control and Expires headers of all documents served from this directory should be set to expire the document 2 weeks after it is served.

The line:

Default-Max-Age=2 weeks after last-mod

specifies the Cache-Control and Expires headers of all documents served from this directory should be set to expire the document 2 weeks after the last-modified date of the document. For more details see the "Max-Age=" file directive.

Default-Wrappers -- Specify a default value for the "Wrappers=" file directive.

The line:

Default-Wrappers=wrapper.html

specifies that this line should be used as the "Wrappers=" file directive for any document in this directory which does not have a Wrappers= directive explicitly set. To override this default value simply specify an explicit "Wrappers=" directive or use "Wrappers=<none>" to have none.

File-Module -- Specify program to be used as interface to database for obtaining files.

If this line specifies a program then instead of looking for a file in the current directory this program is executed after putting the base name of the URL in the environment variable WN_KEY. The output of this program is served as if it were a file. This provides a mechanism to use a real database rather than the file index.cache.

If you wish the file module to have access to all the standard CGI environment variables then use the directive "Default-Attributes=cgi" with the File-Module= directive

Logtype -- Set the type of log entries to be used for this directory matches.

As an example, the line:

Logtype=verbose

will cause logging to be done with WN's verbose log format with no DNS hostnames only IP addresses in the log entries. The base values possible for this directive are nolog, common, verbose, ncsa, syslog and vsyslog which respectively have the effect of turning off logging or using the common log format, WN's verbose logging, or the NCSA log format in the log file or using the syslogd(8) daemon with a standard or verbose format. See the "Managing Log Files" section of this manual. The default value, used when this directive is not present is set in the source file config.h when the compile configure script is run.

Each base log type may be optionally followed by a colon and either nodns or revdns. If neither of these is present then the default server action is to do a DNS lookup on the client's IP address to obtain the hostname of the client for logging purposes. If the :revdns extension is present the server will additionally do a reverse DNS lookup on this name as a check against name spoofing. If the :nodns extension is present the server will do no DNS lookup and will use the IP address in the log instead of the host name. For example the line

Logtype=verbose:nodns

indicates that the server should use verbose log format, but should use IP addresses rather than host names in log entries. Obviously, use of :nodns is more efficient and :revdns is less efficient than the default.

Nomatchsub -- Set substitute file for searches on this directory which result in no matches.

The line:

Nomatchsub=foo.html

specifies that the HTML file foo.html in the current directory should be used for the output of all searches (title, keyword, context, grep, etc.) on this directory which return no matches. It can only be used in conjunction with the "Searchwrapper=" file directive. If Nomatchsub= is used and a "Searchwrapper=" has not been defined an error is logged and the nomatchsub file is ignored. The file foo.html must be in the directory being searched and its name must not contain a '/'. See also "Nomatchsub=" for files.

No-Such-File-URL -- Set substitute URL for requests for non-existent or unservable files.

The line:

No-Such-File-URL=http://host/dir/foo.html

or the line:

No-Such-File-URL=/dir/foo.html

specifies that any request in this directory for a non-existent file or a file not listed in the index.wn file of this directory should be redirected to the given URL. A default value for all directories and non-existent directories can be set by uncommenting the "#define NO_SUCH_FILE_URL" line in config.h and recompiling. The value set here will also be used if an index.cache file does not exist. If you use this directive be sure that the file foo.html does exist or you can create an infinite loop.

Owner -- Specify owner of directory items.

This should be a line like:

Owner=mailto:maintainer@host

The "mailto:maintainer@host" may be replaced with a URL referring to the individual who is responsible for the documents in this directory. This information is used in an HTTP header. It is not possible to designate the owner of a single file in a file directive. However, if the file is an HTML file this can be done with a <link> tag in the header of that file.

Put-Authorization-Module, Put-Authorization-Realm, Put-Authorization-Type -- Specify authorization module for PUT, MOVE and DELETE methods.

In order for the server to honor the PUT, MOVE, and DELETE methods of HTTP, the server must be run with the -P option and in addition an authorization mechanism is required. This can be the same mechanism used for access authorization, or different. Currently WN includes a "basic" authorization module called wnauth. Its use is described in the chapter "Limiting Access to Your WN Hierarchy". Alternatively you can make your own module to handle PUT authorization. Data is placed in CGI environment variables. WN expects this module to exit with status 0 if authorization is granted and with status 1 if access is denied.

For security reasons when you use a "Put-Authorization-Module" you are required to use either the -t or -T options or the -a or -A options and to have the index.cache file in the protected directory owned by the trusted user or group. This is to guard against counterfeit authorization modules.

Finally in the directory where the Put-Authorization-Module directive is used the "Default-Attributes=put" directive must be used (or in the case of a single file the "Attributes=put" directive.)

Put-handler -- Specify a module to handle the PUT, MOVE and DELETE methods. of directory items.

The line

Put-handler=~/dir/puth

tells the server to use the module ROOTDIR/dir/puth to handle the HTTP methods PUT, MOVE and DELETE. A sample put-handler called puth is provided with this distribution. The precise specification of what a put-handler should do is still evolving. The examples/roam directory shows an example of its use for support of the Netscape browser roaming feature.

Search-Module -- Specify program to be used as a search engine.

This directive allows you to create your own search engine. It is invoked with a line like:

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

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

To use this module you should have a form action which is something like http://host/dir/search=index. Two simple examples of a search-module (written in perl) are included in the distribution in the files bin/wnseven_m and bin/wnsectsearch.

Searchwrapper -- Set wrapper file for searches on this directory.

The line:

Searchwrapper=swrap.html

specifies that the HTML file swrap.html in the current directory should be used as a wrapper for the output of all searches on this directory.

To specify a wrapper for searches on an individual file use the file directive "Searchwrapper=".

Subdirs -- Specify subdirectories for searching and recursive use of wndex.

When you run the wndex utility with the -r option (for recursive), it must know in which subdirectories it should descend to create a new index.cache database file. Likewise when the server does a title, keyword or user defined field search it recursively descends the data hierarchy and must know for each directory which subdirectories are part of the hierarchy.

The maintainer provides this information in a line like:

Subdirs=subdir1,subdir2,subdir3

in the directory directives giving a comma separated list of subdirectories of the directory containing the current index.wn file.

There are two special forms of the "Subdirs=" directive. Using:

Subdirs=<index>

is equivalent having a "Subdirs=" directive whose value is a list of all subdirectories which contain a file named "index.wn" (or the name specified with the -i option to wndex).

Using:

Subdirs=<all>

is equivalent having a "Subdirs=" directive whose value is a list of all subdirectories.

B.2 File Directives

A collection of lines in the index.wn file containing information about a single file in the directory of the index.wn file is called a file record. A new file record begins with a line starting with "File=" and ends with the start of a new file record. Each line in a record begins with a file directive. Here is the complete list:

Attributes -- Set file attributes.

Currently several possible attributes are possible including imagemap, nosearch, parse, noparse, post_only, nopost, dynamic, nondynamic, cachable, no-keepalive, non-cachable, put, and cgi. Multiple values, separated by commas can be put on a single "Attributes=" line, as in "Attributes=parse,dynamic,nosearch". Letter case is not significant in the attribute value. Also "Attribute=" (without the 's') is synonymous with "Attributes=".

See also the directory "Attributes=" directive.

Attributes=cachable

causes the server not to send the "Pragma: no-cache" and "Cache-control: no-cache" headers when it otherwise might. For example these headers are sent by default for CGI output. If you want the browser "back" button to return users to a a CGI generated page after they have followed a link you may need "Attributes=cachable" since otherwise the browser may not even cache the page in memory. (See also "Attributes=non-cachable".)

Attributes=cgi

indicates that the standard CGI environment variables should be set up before processing this request. This is may be useful if there is a "Filter=" directive for this document or if the document has a "Include=" which is the output of a program. In these cases the filter program or include program can access the CGI environment variables. This line is not necessary if the document it refers to is actually a CGI program since in that case this attribute is automatically set. If the document is not actually a CGI program then the environment variable PATH_INFO will always be empty. This is because the server always interprets a request without a ".cgi" suffix or a "cgi-bin" directory in it as the longest possible sequence of directories and a terminating file, i.e. a request without PATH_INFO.

Attributes=dynamic

indicates that the document may change each time it is sent. This causes the server not to send headers with a content length or a last modified date. It also will cause the server to ignore any "If-Modified-Since" date sent by the client and always resend the document. It is not necessary to set Attributes=dynamic for CGI programs as it is set by default for them. If you do not wish this done for a CGI program then use the directive "Attributes=nondynamic".

Attributes=imagemap

Indicates that the file is an imagemap used to support clickable images.

Attributes=MD5

Indicates that wndex should calculate an MD5 digest or checksum for this file and store it in the index.cache file for use as in a "Content-MD5" header for this document. If the document is subsequently modified you must re-run wndex to recalculate this digest value. If this is not done and the document is newer than the calculated MD5 digest, the server will omit the "Content-MD5" header and log an error.

Attributes=no-keepalive

indicates that the server should immediately close the connection after fulfiling a request for this document and not honor a request from the client to use a persistent connection.

If this is used as a default attribute and you wish to allow a persistent connection for a specific document then use the line:

Attributes=keepalive

which will override the default.

Attributes=non-cachable

indicates that the server should send the "Pragma: no-cache" and "Cache-control: no-cache" headers attempting to encourage clients and proxies not to cache this document. It is not necessary to set this for CGI programs or any document requiring authentication as it is set by default for them. If you wish to allow the output of a CGI program or authenticated document to be cached then use the line:

Attributes=cachable

which will override this default. This may be necessary if you want the browser "back" button to return users to this document after they have followed a link, since otherwise the browser may not even cache the page in memory.

Attributes=noget

indicates that the file referenced by this directive may not be accessed with the GET method. This might be used with a CGI program designed only to be accessed via the POST method.

Attributes=nondynamic

overrides the default CGI setting of "dynamic". If this is done the "Last-Modified" date header of the document will be that of the program.

Attributes=noparse

indicates that the file referenced by this directive should not be parsed for server includes. This is used to override a default attributes setting to parse all documents. Also this might be done to improve efficiency when, for example, a document has a wrapper but nothing is included in it. Since it has a wrapper parsing will be turned on by default, but it is not necessary since nothing is actually included.

Attributes=nopost

indicates that the file referenced by this directive may not be accessed with the POST method. If the item referenced is an ordinary file this directive is assumed and need not be set. For CGI programs, if this is set and an attempt to POST to the object is made by a client an error will be returned.

Attributes=nosearch

indicates that the file referenced by this directive should not be searched when the server does a context or grep search of the current directory.

Attributes=parse

indicates that the file referenced by this directive should be parsed for conditional text or server-side includes. This line is not necessary if there is also a "Wrappers=" line or an "Includes=" line since in that case the parse attribute is assumed. If you do not wish a document to be parsed when it otherwise would be the "Attribute=noparse" can be used.

Attributes=post_only

indicates that the file referenced by this directive may only be accessed with the POST method. If the item referenced is a CGI program and an attempt is made to access it with the GET method an error will be returned. This directive may useful for files which are filtered or "include" an executed program. In that case the POSTed data will be in placed in a temporary file. The name of the temporary file can be found by using "Attributes=cgi" which will cause the name to be placed in the environment variable WN_POST_FILE.

Attributes=put

indicates that the file referenced by this directive may be accessed with the PUT method. It must be handled by your program. The PUT data will be in placed in a temporary file. The name of the temporary file can be found by using "Attributes=cgi" which will cause the name to be placed in the environment variable WN_PUT_FILE.

CGI-Handler -- Specify the CGI program with which a file is to be processed.

The line:

CGI-Handler=/path/to/bar

causes the program "/path/to/bar" to be run and its output to be served in place of the document requested. This is a way to designate a CGI program to handle a file somewhat like a filter. The name of the program need not be in the URL since it is in the index.wn file. So when http://host/path2/foo.html is requested this will cause the handler, say /path/to/bar, to be run with the CGI environment variable PATH_INFO set to /path2/foo.html. In normal use the program /path/to/bar will do something to the file foo.html and serve the output. It is useful if you want a number of files in a directory to be handled by the same CGI program. Note the file foo.html need not be used in any way by the program, but it must exist or else the server will treat it as a non-existent file.

There is no reason for the CGI-handler program bar to be in the served data hierarchy and it is good security practice to have it be elsewhere in a place where it cannot itself be served. This prevents its execution with the CGI environment variable PATH_INFO been set by the client. It should never be located in a cgi-bin directory. If handler name begins with a '/' the name is considered as a path relative to the system root directory. If it begins with '~/' as in ~/dir/foo it is assumed to be relative to the WN root directory. Otherwise it is assumed to be a path relative to the directory containing the index.wn file.

Charset -- Specify the character set to be added to the MIME type for this document (which should have content type text/*).

The line:

Charset=iso-8859-1

specifies that this document, which should have a MIME type of text/*, should have a character set parameter with this value appended to its content type. E.g. a document of type text/html will be sent with a content type header

Content-type: text/html; charset=iso-8859-1

If no value is specified for this and the Default-Charset directive is not used then the value iso-8859-1 is used. Note, that if a content-type file directive is also used, if must occur AFTER the charset directive.

Content-encoding -- Specify the content encoding for a file.

The line:

Content-encoding=x-gzip

specifies "x-gzip" as the content encoding for the file described by this record. Only two types of content encoding are supported by common browsers. They are "x-gzip" and "x-compress". They indicate that the file has been compressed with the GNU gzip(1) utility or the UNIX compress(1) utility. The file is then sent by the server in the compressed format and will be decompressed automatically by the browser, if it supports this functionality.

In many cases this is unnecessary to specify this explicitly as the wndex program will automatically assign the the content-encoding x-gzip to a file whose name ends with ".gz" and the content-encoding x-compress to a file whose name ends in ".Z". Supplying the value "none" for the "Content-encoding=" will prevent the server from making this automatic assignment.

Content-type -- Specify the MIME content type for a file.

The line:

Content-type=audio/basic

specifies "audio/basic" as the MIME type for the file described by this record. In many cases this is unnecessary as the wndex program will automatically assign the MIME type if the file name ends in a suffix listed in the file lib/mime.types with a corresponding type. If this line is supplied it will override the default value of the content type determined by the suffix.

The mime.types file should be installed in a known location. The default location is in the WN src hierarchy, but this can be changed by specifying a different value when the configure program is run or by editing the value of "#define MIME_TYPES_FILE" in config.h. The 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. A default version of the file is in lib/mime.types. The internal defaults are the same as what is currently in this file. The 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 wnd) on startup for use with directories with the "Attributes=serveall". 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 mime.types file). To do that you need to change the server source and recompile.

Expires -- Specify the expiration date of a document or file.

The line:

Expires=Mon, 01 Sep 1997 14:11:01 GMT

specifies date and time which a document expires. Current practice is to use the format specified by RFC 850 and illustrated above. In particular, GMT should be used. More information about HTTP date formats can be found at RFC 1123. For HTML documents the this information is automatically extracted from the document by wndex. This requires a "<meta>" line in the head of the HTML document like:

<meta http-equiv="Expires" content="Tue, 10 Oct 1994 14:11:01 GMT">

If the "Expires=" directive is also supplied in the index.wn file it will override the expiration date in the document. See also the "Max-age=" file directive.

Field#n -- Specify a user supplied field associated with a file.

The line:

Field3=string

specifies "string" user supplied field 3 associated with the current document. These are used for field searches. The digit 3 can be replaced with any other single digit allowing a total of 10 user supplied fields.

File -- File name.

The line:

File=foo

begins a new file record for the file foo. It indicates that permission is granted for this file to be served. Other file directive lines will apply to this file until a new file record or text segment is started or the end of the index.wn file is reached. The presence of this line causes an entry for this file to be written in the index.cache file created by wndex.

Filter -- Specify the filter with which a file is to be postprocessed.

The line:

Filter=/dir/foo

causes the contents of the file whose record contains this line to be used as the UNIX stdin(3) stream of the program foo and the the UNIX stdout(3) stream of that program to be sent to the client instead of the file itself. A common use of this is to specify a decompressing program like the UNIX zcat(1) utility as the filter so that a compressed version of a file can be stored on disk and then be decompressed on the fly before being sent to the client. Another example would be "Filter=/usr/bin/nroff -man" which would convert a UNIX nroff(1) utility to convert a man(1) page to an ASCII text document on the fly.

If a listed file name begins with a '/' the name is considered as a path relative to the system root directory. If it begins with '~/' as in '~/dir/foo' it is assumed to be relative to the WN root directory. Otherwise it is assumed to be a path relative to the directory containing the index.wn file.

Header -- Add a line to the HTTP/1.1 header for this document.

The line:

Header=[some legal HTTP header]

causes the line "[some legal HTTP header]" to be added to the HTTP/1.1 header for this item. This directive can be used multiple times to add multiple lines to the header.

Note: Don't do this unless you know what you are doing!

HTTP-Status -- Return a given HTTP/1.1 status value.

The line:

HTTP-Status=404 Not Found

causes the response line of the HTTP/1.1 header to be "HTTP/1.1 404 Not Found". This is primarily of use when redirecting requests for non-existent files to an error message which should be returned with status 404 so robots understand.

Note: Don't do this unless you know what you are doing!

Includes -- Specify the files to be included in a text document.

The line:

Includes=file1,file2,file3

causes the file whose record contains this line to be parsed for lines like "". When such a marker is found one of the files listed with the "Includes=" file directive is inserted. Subsequent occurrences of the marker cause the inclusion of subsequent files in the order in which they occur in this directive.

If a listed file name begins with a '/' the name is considered as a path relative to the system root directory. If it begins with '~/' as in "~/dir/foo" it is assumed to be relative to the WN root directory. Otherwise it is assumed to be a path relative to the directory containing the index.wn file. See the section of the user guide on includes and wrappers for more information.

Keywords -- Specify the keywords associated with a document or file.

The line:

Keywords=pink, elephant, HTTP

specifies a list of keywords associated with the current document. These are used for keyword searches. For HTML documents the keywords are automatically extracted from the document by wndex. This requires a <meta> line in the head of the HTML document like:

<meta http-equiv="Keywords" content="pink, elephant, HTTP">

If the "Keywords=" file directive is also supplied in the index.wn file it will override the keywords in the document.

List-Includes -- Specify files which may be included in a text document.

The line:

List-Includes=file1,file2,file3

causes the file whose record contains this line to be parsed for lines like ''. When such a marker is found the contents of file2 is inserted. The order of the files listed in the directive is not significant. Note that the example above grants permission for the inclusion of the three files listed. It does not require their insertion.

Max-Age -- Specify the HTTP/1.1 Cache-Control and Expires headers for an entry.

The line:

Max-Age=10 days

specifies that a HTTP/1.1 Cache-Control header should be sent to expire the document in the specified time. If no "Expires=" file directive has been set elsewhere in the index.wn file or in the file itself, if it is an HTML file, then the HTTP/1.1 Expires header will also be sent with a value equal to the current time plus the time period of the HTTP/1.1 Max-Age header. The time period in the "Max-Age=" file directive can be specified in units of seconds, minutes, hours, days or weeks, but more than one unit (as in 2 weeks and 3 days) is not allowed.

The line:

Max-Age=10 days after last-mod

specifies that a HTTP/1.1 Cache-Control header and the Expires header (if none is set elsewhere) should be set to expire the document in the specified amount of time after the last-modified date of the document. Negative time values for the Cache-Control header will be ignored, but Expires headers with dates in the past will be used.

Nomatchsub -- Set substitute file for searches on this file which result in no matches.

The line:

Nomatchsub=foo.html

specifies that the HTML file foo.html in the current directory should be used for the output of all searches on this file which return no matches. It can only be used in conjunction with the "Searchwrapper=" file directive. See also "Nomatchsub=" for directories.

Redirect -- Send an HTTP/1.1 redirect to a new URL.

The lines:

File=foo Redirect=http://host/path/bar

cause a request for foo to be answered with an HTTP/1.1 redirect response. The client will then automatically request the new URL. The file foo need not exist.

The redirection always sends a HTTP/1.1 "301 Moved Permanently" status header followed by a "Location:" header whose value is "http://host/path/bar". This means that the value of a "Redirect=" file directive should always be a complete URL, starting with "http://" or "ftp://" etc. The one exception is that you may use "Redirect=<null>". This causes the server to send a status 204 "no response" which tells the client to do nothing and leave the display alone. The page won't be reloaded and won't change.

Refresh -- Set a "Refresh" header for use with "client-pull".

The line:

Refresh=60

adds an HTTP/1.1 header at the beginning of the transmission of this document. If the client receiving this header supports "client-pull" (currently only Netscape browsers support this) then it will automatically reload the document after 60 seconds. This is useful for documents that are updated very frequently, a stock ticker, for example. If the directive:

Refresh=30; URL=http://host/path/foo

is used then after 30 seconds the URL http://host/path/foo is loaded. This can be used to create an automatic slide show. The Refresh header is not part of an HTTP/1.1 standard and hence may evolve. If it does this directive will be subject to change!

Searchwrapper -- Set wrapper file for searches on this file.

The line:

Searchwrapper=swrap.html

specifies that the HTML file swrap.html in the current directory should be used as a search wrapper for the output of all searches on this file.

To specify a wrapper for all searches on a directory use the directory directive "Searchwrapper=".

Set-Cookie -- Set a "Cookie" header value.

The lines:

Set-Cookie=name1=opaque1 Set-Cookie=name=xxx; Expires=Wed, 19 Jan 2000 08:49:37 GMT

add an HTTP/1.1 header at the beginning of the transmission of this document. If the client receiving this header supports cookie caching (currently only Netscape browsers browsers support this) then it will save the name=value pairs and include them in the request headers when documents in the same directory or sub-directories are accessed. The server will put the name=value pairs in the CGI environment variable HTTP_COOKIE for access by CGI programs. This is useful for "shopping basket" type applications.

If the value of this directive begins with an '!', as in

Set-Cookie=!my_cookie_script

then it will be interpreted as the name of a program to be run to generate the value of the cookie. The program should not generate the "Set-Cookie:" part of this header, just the value. As elsewhere if the program name starts with '/' it will be taken relative to system root; if it begins with '~' it will be taken relative to the document root; and otherwise it will be assumed to be in the directory where this directive is found. The standard CGI environment variables will be available to the program.

Normally the client will discard the cookie at the end of a session. However, if an Expires parameter like the one above is provided the cookie will be saved between sessions and only discarded when it expires.

More information about the HTTP/1.1 Set-Cookie header is available at http://home.netscape.com/newsref/std/cookie_spec.html.

Title -- Specify the title of a document or file.

The line:

Title=This is the title

specifies the text "This is the title" as the title of the file. If the file is an HTML document this is not necessary as wndex will attempt to read the title from the document itself. If this line is supplied anyway it will override the title in the document. If this line is not supplied and the file is not an HTML document the default title "File <filename>" is used.

Wrappers -- Specify the files to be included in a text document.

The line:

Wrappers=file1

causes "file1" to be parsed for lines like "". When such a marker is found the file whose record contains this line is inserted and the combined document is sent to the client. It is possible to list multiple files in this directive. The semantics of this are explained in the section of the user guide on server-side includes and wrappers.

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