WASD's HTTPd configuration was originally a subset based on the CERN HTTPd. It has now evolved considerably. By default, the system-table logical name HTTPD$CONFIG locates a common configuration file, unless an individual configuration file is specified using a job-table logical name. Simple editing of this file changes the configuration. Comment lines may be included by prefixing them with the hash "#" character. Configuration file directives are not case-sensitive. Any changes to the configuration file can only be enabled by restarting the HTTPd process using the following command on the server system:
$ HTTPD /DO=RESTART
A server's currently loaded configuration can be interrogated. See
11 - Server Administration for further information.
6.1 - Content-Type Configuration
HTTP uses a quasi-standard implementation of the MIME (Multi-purpose Internet Mail Extensions) specification for identifying the type of data returned in a response. A MIME content-type consists of a plain text string describing the data as a type and slash-separated subtype, as illustrated in the following examples:
text/html text/plain image/gif image/jpeg application/octet-streamThe content-type is returned to the client as part of the HTTP response, the client then using this information to correctly process and present the data contained in that response.
In common with most HTTP servers WASD uses a file's type (extension, suffix, e.g. ".HTML", ".TXT", ".GIF") to identify the data type within the file. The [AddType] directive (see below) is used in configuration to bind a file type to a MIME content-type. To make the server recognise and return specific content-types the [AddType] directives matches file types to content-types.
NOTE: When adding a totally new content-type to the configuration be sure also to bind an icon to that type using the [AddIcon] directive (see below). When this is not done a directory listing shows "[?]" in place of an icon.
With the VMS file system there is no effective file characteristic or algorithm for identifying a file's content without an exhaustive examination of the data contained there-in ... a very expensive process (and probably still inconclusive in many cases), hence the reliance on the file type.
If a file type is not recognised (i.e. no [AddType] corresponding to the file type) then by default WASD identifies its data as application/octet-stream (i.e. essentially binary data). Most browsers respond to this content-type with a download dialog, allowing the data to be saved as a file. Most commonly these unknown types manifest themselves when authors use "interesting" file names to indicate their purpose. Here are some examples the author has encountered:
README.VMS README.1ST READ-ME.FIRST BUILD.INSTRUCTIONS MANUAL.PT1 (.PT2, ...)
If the site administrator would prefer another default content-type, perhaps "text/plain" so that any unidentified files default to plain text, then this may be configured by specifying that content-type as the description of the catch-all file type entry. Examples (use one of):
[AddType] * internal/x-unknown - * internal/x-unknown - application/octet-stream * internal/x-unknown - text/plain * internal/x-unknown - something/else-entirelyIt is the author's opinion that unidentified file types should remain as binary downloads, not "text" documents, which they are probably more often not, but it's there if it's wanted.
When accessing files it is possible to explicitly specify the identifying content-type to be returned to the browser in the HTTP response header. Of course this does not change the actual content of the file, just the header content-type! This is primarily provided to allow access to plain-text documents that have obscure, non-"standard" or non-configured file extensions.
It could also be used for other purposes, "forcing" the browser to accept a particular file as a particular content-type. This can be useful if the extension is not configured (as mentioned above) or in the case where the file contains data of a known content-type but with an extension conflicting with an already configured extension specifying data of a different content-type.
Enter the file path into the browser's URL specification field ("Location:", "Address:"). Then, for plain-text, append the following query string:
?httpd=content&type=text/plain
For another content-type substitute it appropriately. For example, to retrieve a text file in binary (why I can't imagine :^) use
?httpd=content&type=application/octet-stream
This is an example:
file.unknown file.unknown?httpd=content&type=text/plain
It is posssible to "force" the content-type for all files in a particular directory. Enter the path to the directory and then add
?httpd=index&type=text/plain
(or what-ever type is desired). Links to files in the listing will contain the appropriate "?httpd=content&type=..." appended as a query string.
This is an example:
*.* *.*?httpd=index&type=text/plain
NOTE: The format of the configuration file has been changed between version 3 and version 4. This was to support on-line server configuration and administration (see 11 - Server Administration). The version 3 format will still be read by the HTTPd but the first time the configuration is updated on-line it is saved in the version 4 format, described below.
The example configuration file for the WASD HTTP server can be viewed.
Some directives take a single parameter, such as an integer, string or boolean value. Other directives can/must have multiple parameters. The version 4 configuration requires the directive to be placed on a line by itself and each separate parameter on a separate line following it. All parameter lines apply to the most recently encountered directive.
Note that all boolean directives are disabled (OFF) by default. This is done so that there can be no confusion about what is enabled and disabled by default. To use directive controlled facility it must be explicitly enabled.
One or more (comma-separated if on the same line) internet host/domain names, with "*" wildcarding for host/subdomain matching, to be explicitly allowed access. If DNS lookup is not enabled hosts must be expressed using numeric addresses (see [DNSLookup] directive). Also see the [Reject] directive. Reject directives have precedence over Accept directives. The Accept directive may be used multiple times.
Examples:
[Accept] *.wasd.dsto.defence.gov.au 131.185.250.*
Specifies the number of days to record activity statistics, available in report form from the server administration menu (see 11.2 - HTTPd Server Reports). Zero disables this data collection. The maximum is 28 days. 11520 bytes per day, and 80640 per week, is required to store the per-minute data.
Specifies a directory listing icon and alternative text for the mime
content type specified in the template.
Examples:
[AddIcon] /icon/-/doc.gif [HTM] text/html /icon/-/text.gif [TXT] text/plain /icon/-/image.gif [IMG] image/gif
[AddBlankIcon] /icon/-/blank.gif [AddDirIcon] /icon/-/dir.gif [DIR] [AddParentIcon] /icon/-/back.gif [<--] [AddUnknownIcon] /icon/-/unknown.gif [???]
Binds a file suffix (extension, type) to a mime content type.
The script name is used to auto-script against a specified file type. The
description is used as documentation for directory listings.
Examples:
[AddType] .html text/html - HyperText Markup Language .txt text/plain - plain text .gif image/gif - image (GIF) .hlb text/x-script /Conan VMS Help library .decw$book text/x-script /HyperReader Bookreader book * internal/x-unknown - application/octet-stream #* internal/x-unknown - text/plain
(Versions prior to 3.2 used this configuration directive for the MIME content-type to determine whether a file was transfered record-by-record or in binary. This is no longer required and should be removed from existing configuration files.)
Enables or disables BASIC username authentication. See 9 - Authentication and Authorization.
The number of minutes authentication information is cached before being revalidated from the authentication source. Zero disables caching (with a resultant impact on performance as each request requiring authentication is validated directly from the source).
Enables or disables Digest username authentication. See 9 - Authentication and Authorization.
The number of seconds a digest nonce for a GET request (read) can be used before becoming stale.
The number of seconds a digest nonce for a PUT (/POST/DELETE ... write) request can be used before becoming stale.
The number of unsuccessful attempts at authentication before the username is disabled. Once disabled any subsequent attempt is automatically refused without further reference to the authentication source. A disabled username can be reenabled by simply purging the cache.
The number of minutes between authenticated requests that user authentication remains valid before the user is forced to reenter the authentication information (via browser dialog). Zero disables the requirement for revalidation.
(Retired in v4.4, server /SYSUAF qualifier provides this)
The maximum number of concurrent client connections before a "server too busy right now ... try again shortly" error is returned to the client.
Granularity of memory blocks allocated to file data, in kilobytes.
Maximum number of files loaded into the cache before entries are reused removing the original contents from the cache.
Maximum size of a file before it is not a candidate for being cached, in kilobytes.
Minimum, total number of hits an entry must sustain before being a candidate for [CacheFrequentSeconds] assessment.
If a file has been hit at least [CacheFrequentHits] times in total and the last was within the number of seconds here specified it will not be a candidate for reuse. See 13 - Cache.
Size of the hash table.
Maximum memory allocated to the cache, in kilobytes.
The interval after which a cache entry's original, content revision time is revalidated against the file's current revision time. If not the same the contents are declared invalid and reloaded.
Includes, as META information, the software ID of the server and any relevant VMS file specification for directory listings, etc.
This value represents time in minutes. If this value is zero CGIplus subprocess may persist indefinitely (excluding explicit and proactive server purging). If non-zero the CGIplus subprocess is terminated the specified number of minutes after it last processed a request. This helps prevent sporadically used scripts from clogging up a system.
Versions of the server prior to 4.3 supplied the full request (header then body) to the script. This was not fully CGI-compliant. Versions 4.3 and following supply only the body, although the previous behaviour may be explicitly selected by enabling this configuration parameter.
The maximum number of DCL/CGI script processing subprocesses that may ever exist concurrently (works in conjunction with [DclSoftLimit].
One or more file type (extension) specification and scripting verb pairs. See 12.3 - Script Run-Time.
The number of DCL/CGI script processing subprocesses after which idle subprocesses are deleted to make room for new ones. The [DclHardLimit] should be approximately 25% more than the [DclSoftLimit]. The margin exists to allow for occasional slow run-down of deleted/finishing subprocesses. If these limits are not set (i.e. zero) they are calculated with [Busy] using "[DclSoftLimit] = [Busy]" and "[DclHardLimit] = [DclSoftLimit] + [DclSoftLimit] / 4".
By default, when a DCL/scripting subprocess is spawned it inherits the server's currently enabled privileges, which are none, not even TMPMBX or NETMBX. If this parameter is enabled the subprocess is created with the server account's SYSUAF-authorized privileges (which should never be other than NETMBX and TMPMBX). Use with caution.
This value represents time in minutes. If this value is zero the use of persistant DCL subprocesses is disabled. If non-zero the zombie subprocess is terminated the specified number of minutes after it last processed a request. This helps prevent zombie processes from clogging up a system. See 12 - Scripting.
The number of minutes a DECnet scripting connection is maintained with the network task. Zero disables connection reuse.
The size of the list used to manage connections for DECnet scripting. Zero effectively allows the server to use as many DECnet scripting connections as demanded.
Controls directory listings. SELECTIVE allows access only to those directories containing a file .WWW_BROWSABLE. The WASD HTTPd directory access facility always ignores directories containing a file named .WWW_HIDDEN. Also see the [DirWildcard] directive.
Retired in v5.0, replaced by [DirDescriptionLines]
Non-Zero enables HTML file descriptions during listings. Generating HTML descriptions involves opening each HTML file and searching for <TITLE>...</TITLE> and <H1>...</H1> text to generate the description. This is an obviously resource-intensive activity and on busy servers or systems may be disabled. Any non-zero number specifies the number of lines to be searched before quitting. Set to a very high number to search all of files' contents (e.g. 999999).
Allows specification of the directory listing layout. This is a short, case-insensitive string that specifies the included fields, relative placement and optionally the width of the fields in a directory listing. Each field is controlled by a single letter and optional leading decimal number specifying its width. If a width is not specified an appropriate default applies. An underscore is used to indicate a single space and is used to separate the fields (two consecutive works well).
The following shows some examples:
[DirLayout] I__L__R__S__D [DirLayout] I__L__R__S:b__D [DirLayout] I__15L__S__D [DirLayout] UI__15L__S__D [DirLayout] 15L__9R__S [DirLayout] 15N_9C_9R_S [DirLayout] I__L__R__S:d__D [DirLayout] 25D:l__S:b__C__R
The size of files is displayed by default as 1024 byte kilos. When using the "S:k", "S:m" and "S:f" size modifiers the size is displayed as 1000 byte kilos. If it is prefered to have the default display in 1000 byte kilos then set the directory listing layout using:
[DirLayout] I__L__R__S:d__D
If unsure of the kilo value being used check the "<META>" information in the directory listing.
When a directory is accessed having no file or type component and there is no welcome page available a directory listing is generated. By default any other directory accessed from this listing has the implied wildcards "*.*" added, consequently forcing directory listings. If enabled, this directive ensures no wildcards are added, so subsequent directories accessed with welcome pages display the pages, not a forced listing.
To prevent browsing through directories (perhaps due to inadvertant mapping) that have file permissions allowing no WORLD access the server stops listing and reports the error the first time a protection violation occurs. This behaviour may be changed to ignore the violation, listing only those files to which it has access.
Allows specification and display of the RMS file owner information.
Directory listings and trees may be pre-expired. That is, the listing is reloaded each time the page is referenced. This is convenient in some environments where directory contents change frequently, but adds considerable over-head and so is disabled by default. Individual directory listings may have the default behaviour over-ridden using syntax similar to the following examples:
/dir1/dir2/*.*?httpd=index?expired=yes /dir1/dir2/*.*?httpd=index?expired=no /tree/dir2/?httpd=index?expired=yes /tree/dir1/dir2/?httpd=index?expired=no
If any of the files provided using the [DirReadMeFile] directive are located in the directory the contents are included at the top or bottom of the listing (or not at all). Plain-text are included as plain-text, HTML are included as HTML allowing markup tags to be employed.
Specifies the names and order in which a directory is checked for read-me files. This can be enabled or disabled using the [DirReadme] directive. Plain-text are included as plain-text, HTML are included as HTML allowing markup tags to be employed.
Examples:
[DirReadMeFile] readme.html readme.htm readme. readme.txt readme.1st
This enables the facility to force the server to provide a directory listing by providing a wildcard file specification, even if there is a home (welcome) document in the directory. This should not be confused with the [DirAccess] directive which controls directory listing itself.
Enables or disables connection request host name resolution. This functionality may be expensive (in terms of processing overhead) and make serving granularity coarser if DNS is involved. If not enabled and logging is, the entry is logged against the numeric internet address. If not enabled any [Accept], [Reject] directive, etc., must be expressed as numeric addresses.
This functionality significantly slows request processing. See 14 - Server Performance.
NOTE: From version 4.4 the HTTPd processes initial client connection at AST delivery level. Some NETLIB-supported TCP/IP packages cannot perform host name resolution at this level and will "hang". If using NETLIB with [DNSlookup] enabled and this seems to occur disable it (NETLIB DNSlookup certainly does work with Digital TCP/IP).
Provides a short message recommending action when reporting an error to a client. For example, if a document cannot be found it may say:
(document, or bookmark, requires revision)
When an error message is generated META information is included showing the server version with source code module and line reporting the error. This is useful information during development and often during general use. Only disable if this concerns you.
(Retired in v4.4, message configuration provides this)
(Retired in v4.4, message configuration provides this)
Number of minutes to allow a connection request to be in progress without submitting a complete request header before terminating it.
Enables or disables the request log. Logging can slow down request processing and adds overhead. The log file name must be specified using the /LOG qualifier or HTTPD$LOG logical name (see Logical Names.
One or more (comma-separated if on the same line) internet host/domain names, with "*" wildcarding for host/subdomain matching, requests from which are not placed in any log files. If DNS lookup is not enabled hosts must be expressed using numeric addresses (see [DNSLookup] directive). Use for excluding local or web-maintainer's host from logs.
Example:
[LogExcludeHosts] *.wasd.dsto.defence.gov.au 131.185.250.*
Specifies one of three pre-defined formats, or a user-definable format. See 6.4.1 - Log Format.
When [LogPeriod] or [LogPerService] directives are used to generate multiple log files this directive may be used to modify the naming of the file. See 6.4.4 - Log Naming.
Specifies a period at which the log file is changed. See 6.4.2 - Log Period.
When multiple services are specified (see 6.3 - Multi-Homed and Multi-Port Services) a separate log file will be created for each if this is enabled. See 6.4.3 - Log Per-Service.
Allows monitoring via the HTTPDMON utility (see 16.5 - HTTPd Monitor. Adds slight request processing overhead.
Number of minutes to allow a request to be output before terminating it.
IP port number for server to bind to.
Maximum size of an HTTP POST or PUT method request in Kilobytes.
File created using the POST or PUT methods have the specified version limit applied.
One or more (comma-separated if on the same line) internet host/domain names, with "*" wildcarding for host/subdomain matching, to be explicitly denied access. If DNS lookup is not enabled hosts must be expressed using numeric addresses (see [DNSLookup] directive). Also see the [Accept] directive. Reject directives have precedence of Accept directives. The Reject directive may be used multiple times.
Example:
[Reject] *.wasd.dsto.defence.gov.au 131.185.250.*
The server can keep a list of the most recent requests accessable from the server administration menu. This value determines the number kept. Zero disables the facility. Each retained request consumes 256 bytes and adds a small amount of extra processing overhead.
Specifies the physical path to the default query-string keyword search script.
Examples:
Search /ht_root/script/query
This parameter allows SSL, multi-homed hosts and multiple port serving to be specified, see 10.1 - SSL Configuration and 6.3 - Multi-Homed and Multi-Port Services.
Enables or disables Server Side Includes (HTML pre-processing).
Enables or disables Server Side Includes (HTML pre-processing) file access counter.
Enables or disables Server Side Includes (HTML pre-processing) DCL execution functionality.
Enables or disables automatic conversion of VARIABLE record format documents (files) to STREAM-LF, which are much more efficient with this server. The integer is the maximum size of a file in kilobytes that the server will attempt to convert. Zero disables the conversion. Also see [StreamLFpaths].
Specifies which path(s) automatic conversion of VARIABLE record format files to STREAM-LF is allowed. If no path is provided all conversion is disabled. To allow conversion on all paths use "/*". Also see [StreamLF].
Example:
[StreamLFpaths] /ht_root/* /web/*
Specifies the names and order in which a directory is checked for home page files. If no home page is found a directory listing is generated.
Examples:
[Welcome] home.html home.htm home.menu home.mnu
By default the server is defined by the local host name and port specified by either [port] or /PORT. The WASD server is capable of concurrently supporting a number of services on different port numbers and, if the system is configured to be multi-homed (see 5.4 - Multi-Homed Hosts With Digital TCP/IP), more than one host name. Using the [Service] configuration parameter or the /SERVICE qualifier the server creates an HTTP service for each specified. If the host name is omitted it defaults to the local host name. If the port is omitted it defaults to 80.
This rather contrived example show a server configured to provide four services over two host names.
[Service] alpha.wasd.dsto.defence.gov.au 8080 beta.wasd.dsto.defence.gov.au beta.wasd.dsto.defence.gov.au:8000
This capability combined with conditional rule mapping (see
8.5 - Conditional Mapping) offers versatile and powerful service
provision. The first port specified in the service list becomes the
"official" port of the server, using the local host name.
6.4 - Access Logging
WASD provides a versatile access log, allowing data to be collected in
Web-standard common and combined formats, as well as
allowing customization of the log record format. It is also possible to
specify a log period. If this is done log files are automatically changed
according to the period specified. Exclude requests from specified hosts
using the [LogExcludeHosts] configuration parameter.
6.4.1 - Log Format
The configuration parameter [LogFormat] and the server qualifier /FORMAT specifies one of three pre-defined formats, or a user-definable format. Most log analysis tools can process the three pre-defined formats. There is a small performance impost when using the user-defined format, as the log entry must be specially formatted for each request.
The user-defined format allows customised log formats to be specified using a selection of commonly required data. The specification must begin with a character that is used as a substitute when a particular field is empty (use "\0" for no substitute, as in the "windows log format" example below).
Two different "escape" characters introduce the following parameters:
A "!" followed by
A "\" followed by
Any other character is directly inserted into the log entry.
Note on "PA" and "RQ"
The "PA" and "RQ" have distinct roles. In general the
"RQ" (request) directive will always be used as this is the full
request string; script component (if any), path string and query string
component (if any). The "PA" directive is merely the path string after
any script and query string components have been removed.
Examples
-!CN - !AU [!TC] \q!RQ\q !RS !BY
-!CN - !AU [!TC] \q!RQ\q !RS !BY \q!RF\q \q!UA\q
\0!TC\t!CA\t!SN\t!AR\t!AU\t!ME\t!PA\t!RQ\t!EM\t!UA\t!RS\t!BB\t
-!CN - !AU [!TC] \q!RQ\q !RS !BY !ES
The access log file may have a period specified against it, producing an automatic generation of log file based on that period. This allows logs to be systematically named, ordered and kept to a managable size. The period specified can be one of
The log file changes on the first request after midnight of the new period. When using a weekly period the new log file comes into effect on the first request following midnight on the specified day.
When using a periodic log file, the file name specified by HTTPD$LOG or the configuration parameter [LogFileName] is partially ignored, only partially because the directory component of it is used to located the generated file name. The periodic log file name generated comprises
HT_LOGS:WASD_80_19971013_ACCESS.LOG
For the daily period the date represents the request date. For the weekly
period it is the date of the previous (or current) day specified. That is, if
the request occurs on the Wednesday for a weekly period specified by Monday
the log date show the last Monday's. For the monthly period it uses the first.
6.4.3 - Log Per-Service
By default a single access log file is created for each HTTP server
process. Using the [LogPerService] configuration directive a log file for each
service provided by the HTTPd is generated (see 6.3 - Multi-Homed and Multi-Port Services).
6.4.4 - Log Naming
When per-period or per-service logging is enabled the access log file has a name generated. Part of this name is the host's name or IP address. By default the host name is used, however if the host IP address is specified the dot-numeric address is used, hyphens being substituted for the periods. Accepted values for the [LogNaming] configuration directive are:
Examples of generated per-service (non-per-period) log names:
HT_LOGS:WASD_80_ACCESS.LOG HT_LOGS:131-185-250-202_80_ACCESS.LOG
Examples of generated per-period (with/without per-service) log names:
HT_LOGS:WASD_80_19971013_ACCESS.LOG HT_LOGS:131-185-250-202_80_19971013_ACCESS.LOG