# Format of rules file

The server configuration file (a.k.a rules file) is a text file that the server reads at program startup and contains commands (rules) that customize the server operation for a particular environment. A rule consists of 1-7 tokens separated by a single semi-colon or a logical line break (a maximum of 8 rules/logical line). You may concatenate several text lines (file records) into a single logical line by placing a backslash as the last character on lines you wish to continue.

## 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, fileexpire
  MST Configuration Rules
    threadpool, service
  Miscellaneous Rules
    # (comment), errorpage, htbin, mapimage, include, proxyscript, search, fileflags
  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 [language-list]
    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.

    The optional language-list argument is a comma-separated list of language codes (e.g. fr,fr-*) that this welcome rule is to apply to. If a language list is specified, the browse will not search the directory for file-name unless an item in the list matches a language named in a accept-language header in the request (or the default language).

    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 [cache-size] [cache-timeout]
    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.

    The optional arguments cache-size and cache-timeout set the number of entries

  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|flags n]
    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.

    The flags keyword specifies a bit mask to enable extended options. Bit 0 enables inclusion of timestamps on each 'active' counter entry (incurring an extra SYS$GETTIM() call on each request), helping to identify hung connections. Bit 1 enables interval counters, which is a shared memory section containing 1 minute snapshots of server activity. Bit 2 selects 'system' mode for interval counters, which uses system locks rather than group global locks.

## 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|exclude] value [template]
    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 transfer units 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.

      The optional template parameter if present makes the rule function as a special translation rule that lets you assign a custom refresh period for url paths that match the template.

    Exclude
      Acts as a special translation rule to let you designate url-paths that are not to be cached. The value argument is the template to match, wildcards are allowed. Note that since this is a translation rule, its position in the configuration file is important.

  fileexpire template [base+]offset
    Causes server to send expires: header with HTTP response when serving files from URL paths that match template. The expiration date will be the file last modified type plus time specified by offset (seconds or hh:mm:ss). The offset parameter may optionally be prefixed by a CDT+ or RDT+ to force offset to be relative to file's create date or modified date (default). Specifying a base of EDT will force the file's expiration date to be used (note that a fileflags must be used to enable retrieval of file expiration times.

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

  errorpage failtype url [ecode]
    Defines special redirect mapping for specified failure types, which lets the webmaster replace the standard error response with a custom page or script.

    failtypes:
      rulefail configuration file mapping failed.
      protfail file protected against access.
      openfail file not found or inaccessible.

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

  fileflags mask
    Sets special file processing options, overiding HTTP_FILE_ACCESS_FLAGS environment variable (default 3). The mask parameter is an integer interpreted as a bit mask:
    0
      If set, filenames to be openned are scanned for ODS-5 'escape'characters and if found the filename will be converted lexically from UNIX syntax to VMS (dev:[dir]fname) syntax.
    1
      If set, filenames are always converted to VMS syntax for passing to fopen().
    2
      If set, special enhance form of fopen() is used which retrieves the file expiration date for use by fileexpire rule processing.

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

# Operation

At server startup, rules file is read sequentially, skipping comments. The presence and/or values of any 'search', 'authenticator', 'suffix', and 'presentation' commands is noted/saved. All other rules are tokenized and saved in a table for processing in the same order that they occur in the rules file.

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.