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, method

Directory Browsing Rules

diraccess, welcome

Protection Rules

authenticator, defprot, hostprot, protect

Logging file Rules

accesslog, dnslookup, tracelevel, eventcounter

Network and Caching Configuration Rules

hostname, localaddress, manage, port, timelimit, filecache

MST Configuration Rules

threadpool, service

Miscellaneous Rules

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

Configuration file pre-processor

.define, .expand, .ignore, .iterate, .next,

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_SYSTEM. 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).

method method [node::["obj-spec"]]handler-script

If request method matches method, invoke script specified by handler-script to handle processing of request. Note that handler-script must be in VMS format, the default directory for the handler script is WWW_SYSTEM. If the handler-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 HEAD and GET methods may not be assigned scripts, the PUT script (WWWPOST.COM) may be re-assigned via this rule.

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 [flags]

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. The optional flags argument is a integer that specifies additional options for the accesslog: if set to 1, access log will include user-agent and referer header information.

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.

(1) 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, the default management host address is changed from 127.0.0.1 (localhost) to the ip-address.

(2) localaddress ip-address hostname

Configures the server to listen for requests on the indicated interface on a multi-homed host and apply subsequent rules only to requests received on that interface. This permits one server to return different root pages based upon the ip-address (domain name) used. The next localaddress rule will close the block of rules specific to the current interface. The ip-address must be specified in numeric 'dot' format.

When using this feature, the default management host address is changed from 127.0.0.1 (localhost) to the first ip-address defined.

(2a) localaddress CNAME hostname

Configures the server to apply subsequent rules only to requests that contain a 'host:' header specifying a host that matches hostname. This permits a server with 1 ip-address but multiple domain name aliases (DNS CNAME records) to return different root pages based upon the domain name used. The next localaddress rule will close the block of rules specific to the current hostname. Note that old browser's may not supply a host header with their requests.

(3) localaddress

Terminates last localaddress block, subsequent rules will apply to all request regardless of the interface used.

manage [host host-addr|port port-num|script script-name [commands]]

Controls access to the management interface to performing maintenance and diagnostics functions on the server via the privrequest program and/or management scripts (servermaint). Only scripts named in 'manage script' rules may issue <DNETMANAGE> tags.

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.

timelimit keyword timeout [count]

Sets timeouts period of network and script operations by keyword:

Request

Sets time limit for receipt of HTTP request from client.

Response

Sets time limit for sending of response after request recieved.

Keep-alive

Set time limit for reciept of next request for connections kept open using the connection: keep-alive HTTP request header.

ScriptDialog

Sets time limit for completion of 'dialog' phase of script-server interaction

ScriptOutput

Sets time limit for completion of 'output' phase of script-server interaction

ScriptReuse

Set the length of time the server will keep maintain a script connection marked for reuse. Specifying a count parameter will allow that many connection to be exempt from this timeout (i.e. 'permanent').

The timeout parameter may be specified as an integer number of seconds; hours, minutes, seconds (hh:mm:ss); or the name of an environment variable containing one of those 2 formats.

The count parameter, used only for Keep-alive and ScriptReuse, is an integer value specifying either the maximum number of times a connection is re-used or the number of 'permanent' DECnet connections to keep active.

filecache [size|limit|maxrec|refresh] value

Set file cache parameter. The file cache is used to store copies of of recently served files, improving performance by bypassing most of the overhead of the C RTL.

Size

Sets total number of bytes available for file caching to the number specified in the value parameter. The total number of files that can be cached is a function of the cache size and allocation granularity and is roughly value/MaxRec (see below).

Note that the total cache size is allocated from heap at server startup and consumes process pagefile quota, a very large cache may result in a decrease in client limit.

Limit

Sets maximum size for an individual cache entry. If a file exceeds value bytes, the data will not be cached, but the entry will be maintained for allowing efficient response to HEAD request and if-modified-since HTTP request headers.

MaxRec

Sets maximum size for a record entry in the cache, indirectly setting the allocation granularity for the cache. Default maxrec is 16000 bytes, minimum allowed is 4096. Note that cache 'records' are are blocking factors for cache get/put operations and not a limitation on the logical record size of files stored in the cache.

Refresh

Sets the expiration time for cache entries. When a new cache entry is created, it adds the refresh time to the the current time to get an expiration time. When a entry is accessed, the current time is compared to that entry's expriation time and if expired will cause the cache to verify the last modification date on the source with the cached value. If the entry is still valid, a new expiration time is computed. A refresh time of zero (0) is allowed.

The timeout parameter may be specified as an integer number of seconds; hours, minutes, seconds (hh:mm:ss); or the name of an environment variable containing one of those 2 formats.

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. /demo/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?).

proxyscript path

Sets action server is to take when a client attempts to use the server as a proxy-gateway server. All proxy requests are mapped to path and processed accordingly. If path refers to a file (e.g. /demo/nogateway.html), that file is returned. Alternatively, a script may be specified (.e.g. /htbin/proxygw).

Note that the proxyscript mapping occurs before any other translation rules and only one proxyscript may be specified.

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).

Pre-processor Directives

Pre-processor directives are special rules that are executed prior to the standard parsing step which then acts upon the result of the pre-processing expansion (much like the C language pre-processor). Pre-processor directives begin with a period. There are 5 general directives that the server actively executes and an arbitirary number of additional directives for private use by maintenance scripts (they are recognized and ignored).

The pre-processor directive operate on the entire logical line, allowing you to define macros with several rules.

.define symbol value

Defines a symbol for use with the .expand command

.expand command-template

Scans command-template and replaces any tokens of form $symbol with the definition from a previous .define directive. The completed command is then interpreted as a normal command.

.ignore directive-list

Defines additional directives that server will recognize but ignore ( generating no errors). This provides a means for additional information needed by the maintainence script (e.g. .authorize records) to be saved in the configuration file

.iterate command-template

Save the command template for reference by subsequent .next directives, build a dummy argument list for each token of form $name.

.next arguments

Insert arguments into dummy argument list (in order) and perform .expand on the saved command-tempate.

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.