Format of rules file

Directory:

Select link to jump directly to section of interest.

Translation Rules

exec, fail, map, pass, redirect, userdir, usermap

Data Mapping Rules

suffix, presentation

Directory Browsing Rules

diraccess, welcome

Protection Rules

authenticator, defprot, hostprot, protect

Logging file Rules

accesslog, dnslookup, tracelevel, eventcounter

Network Configuration Rules

hostname, localaddress, port

MST Configuration Rules

threadpool, service

Miscellaneous Rules

# (comment), htbin, mapimage, include, search

Operation

Translation Rules

Translation rules screen and direct processing of request based upon its URL.

exec dir-template [%service:|node::["obj-spec"]]script-directory

If URL matches dir-template, invoke script in corresponding script directory specified by script-directory. Note that dir-template must be in unix format (/dir/dir...) and script-directory must be in VMS format (disk[dir]). If the script-directory is prefixed with a DECnet node, the script task will be started on that node instead of the default (0:: or node part of WWWEXEC logical). If the script-directory is prefixed with a MST service name (flagged by '%' and ':'), the script will be handled by an internal connection to a service thread.

fail template

Prohibit access to addresses matching template.

map template result

If address matches template, use result string for future rules. Template and result must be in unix file specification format (/device/dir/dir/...).

pass template [result]

if address matches the template, use it as is. If result argument is present, perform map operation and use translation.

redirect template url

If address matches template, a redirect will be sent to the client redirecting it to the specified URL. The URL must be in absolute format (include scheme and host). Local redirects are redundant since they can be handled by map directives.

userdir sub-dir

if address matches template /~username/xxx, replace with /device/directory/sub-dir/xxx where device and directory are specified username's default device and directory. Note that sub-dir string must not have a leading slash. (e.g. userdir web).

usermap template map-arg rtn,image,[dir]

if address matches template, call user-supplied mapping routine specified by rtn,image,[dir] (loaded at startup via LIB$FIND_IMAGE_SYMBOL). The mapping routine can rewrite the address and return a code to either continue with the next rule (effecitively a Map rule) or exit with success or failure (Pass, Redirect, Exec, Fail). The map-arg argument may be used to pass configuration data to the map routine.

Data Mapping Rules

The data mapping rules suffix and presentation control how the server reads and presents the contents of the files it serves.

suffix [.sfx|*|*.*] data-type encoding[/ce] [quality]

Bind data-type to file suffix. Special values for suffix fields are * (match any file that hasn't matched another suffix) and *.* ( (match file with suffix that hasn't matched another suffix). The data-type field is the MIME content-type. Encoding is the content transfer encoding to use (only binary, 8bit, 7bit supported) with an optional content encoding (e.g. x-gzip).

presentation data-type [node::["obj-spec"]]converter-script

If data-type of document matches data-type, use converter script specified by converter-script to convert document, returning result to client instead of original document. Note that converter-script must be in VMS format, the default directory for the converter script is WWW_ROOT:[000000]. If the converter-script is prefixed with a DECnet node, the script task will be started on that node instead of the default (0:: or node part of WWWEXEC logical).

For directory URLs (ends in slash) the server checks for a presentation definition of the implied data type text/file-directory and will invoke the corresponding converter script if found. Note that when a text/file-directory converter is used, the config file's browser rules do not apply (i.e. the converter has it's own configuration file).

Directory Browsing Rules

The directory browsing rules diraccess and welcome control how the server processes requests where the URL specifies a directory.

diraccess [on|off|selective [control-file]]

Enables/Disables directory browsing. Specifying a keyword of "on" (the default) enables the server to generate directories while the keyword "off" disables browsing. The "selective" keyword makes the browsing conditional upon the existence in that directory of a control file (default: .www_browsable).

welcome file-name

Adds file-name to list of default file names to search for when the requested URL is a directory (ends in slash). The files are searched for in the same order as they appear in the configuration file. If one of the files is found, the server sends a redirect to the client directing it to that filename.

If no welcome directives are defined, the server uses a default list of index.html, index.htmlx for compatibilty with previous releases. Defining a presentation rule for data type text/file-directory will take precedence over any welcome file definitions.

Protection Rules

The protection rules restrict access to the server resources based upon who the user is.

authenticator image

The authenticator rule specifies the name of the authenticator image used to validate accesses to files protected with protect rule. This image is run by a sub process created by the server at initialization. If an authenticator is not present, any attempts to access files protected by protect rules will automatically fail.

defprot dir-template protection-setup-file

Sets default protection setup file for protect and hostprot directives.

hostprot template [protection-setup-file]

Same as protect command below except that simpler (level 1) protection checks take place. Only maskgroup directives in setup file are processed and only items without usernames (i.e. @xxx.xxx.xxx.xxx) are checked. Note that authenticator does not have be run in order to use hostprot.

protect dir-template [protection-setup-file]

If address matches dir-template, validate access against that granted by corresponding protection setup file. The setup file may be sepcified in either UNIX or VMS format.

Logging File Rules

The server has 2 different log files. The access log records each access using the common server log format for use by programs like getstats. The trace/error log is used by the server to report diagnostic information.

accesslog logfile

Enables logging of client accesses to specified log file using 'common' Web server log file format. The specified file (VMS or UNIX format) is opened for append or created if it does not exist.

dnslookup [on|off]

Enables/Disables Domain Name Server lookups of the host names for remote clients. If disabled (the default), the log file reports the host by IP address.

tracelevel level [tracefile]

Set trace level and trace file for debugging. You may specify level as either a numeric constant or an environment variable (DCL symbol) name. The trace level has the same meaning as the environment variable http_log_level and will override it. The optional tracefile parameter specifies a separate file to record the trace, if missing, trace entries will go to the standard error log file.

eventcounter [clients|hostclass class [~]mask]

Define or enable event counters. The clients counter, when enabled, counts number of connections and keeps a histogram of concurrency (overlap) of the requests.

The hostclass counter, when enabled, causes the server to compare the remote client address against each hostmask and increment the counter for the corresponding class. Hostmask is an ip-address or, if DNSLookup is on, domain name. A single asterik may be used to wildcard labels (strings delimited by periods) in the mask.

A mask prefixed with a tilda (~) negates the sense of the test. For a counter to be incremented, at least one non-negated mask must match or none of the negated hosts must match.

Network Configuration Rules

The network configuration rules control how the server presents itself to the TCP/IP network.

hostname name

Sets the name the server will use when generating redirects. If this rule is not present in the rule file, the server will use the environment variable HTTP_DEFAULT_HOST.

localaddress ip-address

Configures the server to listen for requests on a specific interface on a multi-homed host. This permits one host to run multiple servers with a different configuration file for each ip-address homed to that host. The ip-address must be specified in numeric 'dot' format.

When using this feature, you must also set the environment variable HTTP_MANAGE_HOST so that the server can receive management commands from the right interface.

port port-num [nocache-port]

Sets the port number the server will listen for connections on, overriding the command line argument. If the optional nocache-port is present, server will listen on that port as well but bypass the cache (if present) when serviing requests. You may specify port or nocache-port as either a numeric constant or an environment variable (DCL symbol) name. The nocache port may be the same as the regular port.

If rule not present, default is 80 or 3rd command line argument if not null.

MST Configuration Rules

The MST configuration rules control the creation and attributes of MSTs (Message-based Service Threads) and bind service names to MST start routines for these threads. The service name, when specified as the target 'node' in a exec rule, causes an MST to be created to service the script request rather than a DECnet task.

threadpool pool-name [keyword=value ...]

Creates a thread pool with specified attributes and assigns it indicated name. Attributes keywords: stack - thread stack size; q_flag - Indicates (1/0) whether connect should wait for available thread or fail immediately; limit - Maximum number of threads in pool.

service service-name [keyword=value [...]]

Define service name for an MST scriptserver and assign its attributes. Attributes keywords: pool - name of thread pool to use; builtin - scriptserver start routine (mapimage, cgifork); dynamic - shareable image scriptserver (start,image[,dir]); info - optional argument; init - share image init routine.

Miscellaneous Rules

Other rules.

# comment

A comment line is denoted by beginning the line with the # character. Comment lines are ignored by the server.

htbin directory (obsolete)

Superceded by exec directory, for compatibility this directive is mapped internally to "exec /htbin/* directory".

mapimage [prefix]

Defines special script that handles image maps by internal calls in the server. In anchors containing <IMG> tags, specify a HREF of the form HREF="/$mapimage/conf-file" where prefix/conf-file is a virtual path (e.g. /www/documents/nagel23a.imagemap) to the imagemap configuration file. The prefix, if specified, effectively limits the input files for the builtin mapimage to those in a known directory tree.

include config-file

Read specified file and process records as if they were being read from original file at the point of the include statement. Includes may be nested to 20 levels (who would do that?).

search [node::["obj-spec"]]search-script

Enables general search function. When a non-exec URL contains a search argument, the script specified by search-script is invoked to perform that search (subfunction SEARCH). Note that search-script must be in VMS format, the default directory for the script is WWW_ROOT:[000000]. If the search-script is prefixed with a DECnet node, the script task will be started on that node instead of the default (0:: or node part of WWWEXEC logical).

The ident portion of a URL is translated by making a unescaped copy of it in a work area and testing the work area copy against each entry in the tokenized rule list. A rule that matches against the translation in the work area may rewrite the translation (see map rule), subsequent tests for triggering rules will be made against the new translation.

The data from suffix rules is kept in a different data structure optimized for finding highest quality representation supported by a client request.