Server configuration basically concerns itself the very fundamental behaviour of the server process. Requirements such as buffer and cache sizes, timeout values, scripting limits, content-types, icons, number and type of services offerted, etc., are determined from configuration information.
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
14 - 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
The WASD server is capable of concurrently supporting the same host name on different port numbers and a number of different host names (aliased or multi-homed) using the same port number. This capability is generally known as a virtual server. Virtual services offer versatile and powerful multi-site capabilities using the one system and server process. Service determination is based on the contents of the request's "Host:" header field. If none is present it defaults to base service for the interface's IP address and port.
The same mechanism also effectively allows a single instance of the configuration files to support multiple server processes (using the /SERVICE qualifier), either on the one system or across multiple systems, as in a cluster (i.e. supports "virtual" and "real" servers.) See STARTUP_SERVER.COM for further information on startup support for these configurations.
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. The first port specified in the service list becomes the "administration" port of the server, using the local host name, appearing in administration reports, menus, etc. This port is also that specified when sending control commands via the /DO= qualifier (see 5.3.2 - Server Command Line Control).
This rather contrived example show a server configured to provide four services over two host names.
[Service] alpha.wasd.dsto.defence.gov.au alpha.wasd.dsto.defence.gov.au:8080 beta.wasd.dsto.defence.gov.au beta.wasd.dsto.defence.gov.au:8000
WASD provides server process run-time parameters via the HTTPD$CONFIG
configuration file. These provide settings for logging, scripting, timeouts,
file content-type mappings, etc. The HTTPD$MSG file provides configurable
system messages.
[[virtual-server]]
The essential profile of a site is established by it's mapped resources and any authorization controls, the HTTPD$MAP and HTTPD$AUTH configuration files respectively, and these two files support directives that allow configuration rules to be applied to all virtual services (i.e. a default), to a host name (all ports), or to a single specified service (host name and specific port).
To restrict rules to a specified server (virtual or real) add a line containing the server host name, and optionally a port number, between double-square brackets. All following rules will be applied only to that service. If a port number is not present it applies to all ports for that service name, otherwise only to the service using that port. To resume applying rules to all services use a single asterisk instead of a host name. In this way default (all service) and server-specific rules may be interleaved to build a composite environment, server-specific yet with defaults. Note that service-specific and service-common rules may be mixed in any order allowing common rules to be shared. This descriptive example shows a file with one rule per line.
# just an example this rule applies to all services so does this and this one [[alpha.wasd.dsto.defence.gov.au]] this one however applies only to ALPHA, but to all ports as indeed does this [[beta.wasd.dsto.defence.gov.au:8000]] now we switch to the BETA service, but only port 8000 another one only applying to BETA and a third [[*]] now we have a couple default rules that again apply to all servers
Both the mapping and authorization modules report if rules are provided
for services that are not configured for the particular server process (i.e.
not in the server's [Service] or /SERVICE parameter list). This provides
feedback to the site administrator about any configuration problems that
exist, but may also appear if a set of rules are shared between multiple
processes on a system or cluster where processes deliver differing services.
In this latter case the reports can be considered informational, but should be
checked initially and then occasionally for misconfiguration.
Unknown Virtual Server
If a service is not configured for the particular host address and port of a request one of two actions will be taken.
[ServiceNotFoundURL] //server.host.name/httpd/-/servicenotfound.html
pass /*/-/admin/* pass /*/-/* /ht_root/runtime/*/* exec /cgi-bin/* /cgi-bin/* [[virtual1.host.name]] /* /web/virtual1/* / /web/virtual1/ [[virtual2.host.name]] /* /web/virtual2/* / /web/virtual2/ [[virtual3.host.name]] /* /web/virtual3/* / /web/virtual3/ [[*]] /* /web/servicenotfound.html
This applies to dotted-decimal addresses as well as alpha-numeric. Therefore if there is a requirement to connect via a numeric IP address such a service must have been configured.
Note also that the converse is possible. That is, it's possible to
configure a service that the server cannot ever possibly respond to because it
does not have an interface using the IP address represented by the service
host.
6.3 - Error Reporting
By default the server provides it's own internal error reporting facility. In addition the [ErrorReportPath] configuration directive allows a redirection path to be specified for error reporting, allowing the site administrator to tailor both the nature and format of the information provided. A Server Side Include document, CGI script or even standard HTML file(s) may be specified. An SSI document is recommended for it's simplicity yet versatility.
Site-specific error reporting works by internal redirection. When an error
is reported the original request is concluded and the request reconstructed
using the error report path before internally being reprocessed. Error
information becomes available via a specially-built query string, and from
that as CGI variables in the error report context. One implication is the
original request path and query string are no longer available. All error
information must be obtained from the error information in the new query
string.
Using an SSI Document
Three example SSI error report documents are provided.
It is suggested with any use of this facility the reporting document(s) be located somewhere local, probably HT_ROOT:[LOCAL], and then enabled by placing the appropriate path into the [ErrorReportPath] configuration directive, as shown for the examples here
[ErrorReportPath] /ht_root/example/reporterror1.shtml
Note that virtual services can subsequently have this path mapped to other documents (or even scripts) so that some or all services may have custom error reports.
The following SSI variables are available specifically for generating error reports. The <!--#printenv --> statement near the top of the file may be uncommented to view all SSI and CGI variables available.
It is also possible to report using a script. This is discouraged dues to
it's relative complexity, and should only be undertaken for verify specific
reasons of limitation within the SSI implementation. The source code
HT_ROOT:[SRC.MISC]REPORTERROR.C
provides such an implementation example.
Using HTML Documents
SSI documents are the obvious choice for reporting errors but they do take time and CPU for processing, and this may be a significant consideration on busy sites. If prefered, static HTML documents may be used to report errors. Generally one per possible response error status code is required. When providing a error report path including a "!UL" introduces the response status code into the file path, providing a report path that includes a three digit number representing the error. A file for each possible number must then be provided.
[ErrorReportPath] /ht_root/local/reporterror!UL.html
This mapping will generate paths such as the following, and require at least these to respond to general errors.
/ht_root/local/reporterror400.html /ht_root/local/reporterror401.html /ht_root/local/reporterror403.html /ht_root/local/reporterror404.html /ht_root/local/reporterror500.html /ht_root/local/reporterror501.html /ht_root/local/reporterror502.html /ht_root/local/reporterror503.html
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.2 - Virtual 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