<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Server Configuration\chapter_config)

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

<P> 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
<QUOTE>(#) 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.

<CODE_EXAMPLE>
  $ HTTPD /DO=RESTART
<ENDCODE_EXAMPLE>

<P> A server's currently loaded configuration can be interrogated.  See
<REFERENCE>(chapter_server_admin) for further information.

<HEAD1>(<QUOTE>(Securing) The Site\head_config_securing)

<P> This section does not pretend to be a complete guide to keeping the
<QUOTE>(bad guys) out.  It does provide a short guide to making a site
more-or-less liberal in the way the server supplies information about the site
and itself.  The reader is also strongly recommended to a number of hard and
Web based resources on this topic.

<P> The WASD package had it's genesis in making the VMS operating system and
associated resources, in a development environment, available via Web
technology.  For this reason the default configuration is fairly liberal,
providing information of use in a technical environment, but that may be
superfluous or less-than-desirable in other, possibly commercial environments. 
For instance, directory listings can contain VMS file system META information,
error reports can be generated with similar references along with reporting
source code module and line information.  This section refers to configuration
directives discussed in more detail later in this chapter and in the next.

<HEAD2>(Directory Listings\config_securing_directory)

<P> Published guidelines for securing a Web site generally advise against
automatic directory listing generation.  Where a home page is not available
this may leak information on other directory contents, provide parent and child
directory access, etc.  Compounding this is the WASD facility to
<EMPHASIS>(force) a listing by providing a directory URL with file wildcards
(not to decry it's usefulness in some environments).

<LIST>(unnumbered)

<LE> <EMPHASIS>([DirAccess] - \BOLD)
Make <QUOTE>(disabled) to completely remove the ability to generate directory
listings under any circumstances.  Setting to <QUOTE>(selective) means a
directory listing is <EMPHASIS>(only\BOLD) available if the directory contains
a file named .WWW_BROWSABLE.  When made <QUOTE>(enabled) a directory listing
may be produced anytime it contains no home (welcome) page.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirWildcard] - \BOLD)
Make <QUOTE>(disabled) so that requests cannot <EMPHASIS>(force\BOLD) a
directory listing by supplying a URL containing a wildcard file part (when
enabled this is provided regardless of whether a home page exists or not). 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirMetaInfo] - \BOLD)
Make <QUOTE>(disabled) to prevent directory listing pages contain as HTML
<LITERAL>(<META>) tags information about the directory, most significantly the
VMS file specification for the URL path!

<ENDLIST>

<HEAD2>(Server Reports\config_securing_reports)

<P> Reports are pages generated by the server, usually to indicate an error or
other non-success condition, but sometimes to indicate success (e.g. after a 
successful file upload).  Reports provide either basic or detailed information
about the situation.  Sometimes the detailed information includes VMS file
system details, system status codes etc.  To limit this information to a
minimum indication adjust the following directives.

<LIST>(unnumbered)

<LE> <EMPHASIS>([ReportBasicOnly] - \BOLD)
Make <QUOTE>(enabled) to limit the quantity of information to the minimum
required to advise of the situation.  Such reports give only the HTTP status
code and brief explanation of the code's meaning.  Note that this can also be
done on a per-path basis using mapping rules.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ReportMetaInfo] - \BOLD)
Make <QUOTE>(disabled) to exclude information on the server software, source
code module and line number initiating the report.  META information may also
contain VMS file or system specific information.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServerSignature] - \BOLD)
Make <QUOTE>(disabled) to prevent the inclusion of server software, host and
port information as a footer to a report.

<ENDLIST>

<HEAD2>(Scripting\config_securing_scripting)

<P> Scripting has been a notorious source of server compromise, particularly
within Unix environments where script process shell command-line issues require
special attention.  The WASD CGI scripting interface does not pass any
arguments on the command line, and is careful not to allow substitution when
constructing it's CGI environment.  Never-the-less, script behaviours cannot be
guranteed and care should be exercised in their deployment.

<LIST>(unnumbered)

<LE> <EMPHASIS>([Scripting] - \BOLD)
Setting this to <QUOTE>(disabled) prevents all scripting entirely.  This
includes subprocess CGI and CGIplus, DECnet-based OSU and CGI, and SSI
subprocess DCL (<LITERAL>(<--#dcl -->), <LITERAL>(<--#exec -->), etc.).

<ENDLIST>

<HEAD2>(Server Side Includes\config_securing_ssi)

<P> SSI documents are pages containing special markup directives interpreted by
the server and replaced with dynamic content.  This can include detail about
the server, the file or files making up the document, and can even include DCL
commands and procedure activation for supplying content into the page.  All
this by anyone who can author on the site.

<LIST>(unnumbered)

<LE> <EMPHASIS>([SSI] - \BOLD)
Setting this to <QUOTE>(disabled) prevents all Server Side Include processing
completely.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([SSIexec] - \BOLD)
Setting this to <QUOTE>(disabled) disallows pages from invoking subprocess DCL
to supply content for the page.  WASD provides a number of levels of this and
the reader is refered elsewhere in this and other documents for further
infromation of what can and cannot be done, and by whom, in these subprocesses.

<ENDLIST>

<HEAD2>(Authorization\config_securing_auth)

<P> Authorization issues imply controlling access to various resources and
actions and therefore require careful planning and implementation if compromise
is to be avoided.  WASD has a quite capable and versatile authorization and
authentication environment, with a significant number of considerations.  The
reader refered to the chapter on this topic, 
<REFERENCE>(chapter_authorization).

<P> WASD authorization cannot be enabled without the administrator configuring
at least three resources, and so therefore cannot easily be
<QUOTE>(accidentally) activated.  One of these is the addition of a startup
qualifier controlling where authentication information may be sourced.  Another
the server configuration file.  The third, mapping paths against authorization
configuration.

<P> For sites that may be particularly sensitive about inadvertant access to
some resources it is possible to use the authorization configuration file as a
type of <EMPHASIS>(cross-check) on the mapping configuration file.  The server
/AUTHORIZATION=ALL startup qualifier forces all access to be authorized (even
if some are marked <QUOTE>(none)).  This means that if something
<QUOTE>(escapes) via the mapping file it will very likely be <QUOTE>(caught) by
an absence in the authorization file.

<HEAD2>(Miscellaneous Issues\config_securing_misc)

<P> Although it is of limited usefulness because server identity may be deduced
from behaviour and other indicators the exact server and version may be
obscured by using the otherwise undocumented /SOFTWARE= qualifier to change the
server identification string to (basically) whatever the administrator desires. 
This identification is included as part of all HTTP response headers.

<P> Historically and by default server configuration and authorization sources
are contained within the server package tree.  There is no reason why they
cannot be located anywhere the site prefers.  Generally all that is required is
a change to logical name definition and server startup.

<HEAD>(Package Tree\config_securing_package)

<P> On many sites there may be little need to access the full, or any of the
WASD package tree.  A combination of mapping and/or authorization rules can
relatively simply block or control access to it.  These examples can be easily
tailored to suit a site's specific requirements.

<P> This example shows blocking all access to the /ht_root/ tree, except for
documentation, source code, examples and exercise (performance results) areas.

<CODE_EXAMPLE>
  # HTTPD$MAP
  pass /ht_root/doc/*
  pass /ht_root/src/*
  pass /ht_root/example/*
  pass /ht_root/exercise/*
  fail /ht_root/*
<ENDCODE_EXAMPLE>

<P> The next example forbids all access to the package tree unless authorized 
(the authorization detail would vary according to the site).  It also allows
modify access for the Admin Menu and to the /ht_root/local/ area.

<CODE_EXAMPLE>
  # HTTPD$MAP
  pass /ht_root/*

  # HTTPD$AUTH
  [WASD_WEB_ADMIN=id]
  /httpd/-/admin/* r+w
  /ht_root/local/* r+w
  /ht_root/* r
<ENDCODE_EXAMPLE>

<HEAD1>(Content-Type Configuration\head_config_content_type)

<P> 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 <EMPHASIS>(type) and slash-separated
<EMPHASIS>(subtype), as illustrated in the following examples:

<CODE_EXAMPLE>
  text/html
  text/plain
  image/gif
  image/jpeg
  application/octet-stream
<ENDCODE_EXAMPLE>

<CP> The 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.

<P> In common with most HTTP servers WASD uses a file's type (extension,
suffix, e.g. <QUOTE>(.HTML), <QUOTE>(.TXT), <QUOTE>(.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

<COMMENT>(HTML=&quot;<FONT COLOR="#ff0000"><B>[?]</B></FONT>&quot;)
<COMMENT>(HTML/OFF)
<QUOTE>([?])
<COMMENT>(HTML/ON) 

in place of an icon.
<ENDNOTE>

<P> 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 <HELLIPSIS> a very expensive process (and
probably still inconclusive in many cases), hence the reliance on the file
type.

<P> If a file type is not recognised (i.e. no [AddType] corresponding to the
file type) then by default WASD identifies its data as
<EMPHASIS>(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 <QUOTE>(interesting) file names to indicate their
purpose. Here are some examples the author has encountered:

<CODE_EXAMPLE>
  README.VMS
  README.1ST
  READ-ME.FIRST
  BUILD.INSTRUCTIONS
  MANUAL.PT1 (.PT2, <HELLIPSIS>)
<ENDCODE_EXAMPLE>

<P> If the site administrator would prefer another default content-type,
perhaps <QUOTE>(text/plain) so that any unidentified files default to plain
text, then this may be configured by specifying that content-type as the
<EMPHASIS>(description) of the catch-all file type entry. Examples (use one
of):

<CODE_EXAMPLE>
  [AddType]
  *  internal/x-unknown  -
  *  internal/x-unknown  -  application/octet-stream
  *  internal/x-unknown  -  text/plain
  *  internal/x-unknown  -  something/else-entirely
<ENDCODE_EXAMPLE>

<CP> It is the author's opinion that unidentified file types should remain as
binary downloads, not <QUOTE>(text) documents, which they are probably more
often not, but it's there if it's wanted.

<HEAD>(Explicitly Specifying Content-Type\head_explicit_type)

<P> 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-<QUOTE>(standard) or non-configured file
extensions.

<P> It could also be used for other purposes, <QUOTE>(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.

<P> Enter the file path into the browser's URL specification field ("Location:",
"Address:").  Then, for plain-text, append the following query string:

<CODE_EXAMPLE>
  ?httpd=content&type=text/plain
<ENDCODE_EXAMPLE>

<P> For another content-type substitute it appropriately. 
For example, to retrieve a text file in binary (why I can't imagine :^) use

<CODE_EXAMPLE>
  ?httpd=content&type=application/octet-stream
<ENDCODE_EXAMPLE>

<P> This is an example:

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<PRE>
  <A HREF="file.unknown">file.unknown</A>

  <A HREF="file.unknown?httpd=content&type=text/plain">file.unknown?httpd=content&type=text/plain</A>
</PRE>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<P> It is posssible to "force" the content-type for all files in a particular
directory.  Enter the path to the directory and then add

<CODE_EXAMPLE>
  ?httpd=index&type=text/plain
<endCODE_EXAMPLE>

<P> (or what-ever type is desired).  Links to files in the listing will contain
the appropriate <QUOTE>(?httpd=content&type=...) appended as a query string.

<P> This is an example:

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<PRE>
  <A HREF="*.*">*.*</A>

  <A HREF="*.*?httpd=index&type=text/plain">*.*?httpd=index&type=text/plain</A>
</PRE>
)

<COMMENT>(....................................................................)

<HEAD1>(Virtual Services\head_virtual_services)

<P> The WASD server is capable of concurrently supporting the same host name on
different port numbers and a number of different host names (DNS aliased or
multi-homed) using the same port number. This capability is generally known as
a <EMPHASIS>(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 <QUOTE>(Host:) header
field.  If none is present it defaults to base service for the interface's IP
address and port.

<P> 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 <QUOTE>(virtual) and <QUOTE>(real) servers.) See
<REFERENCE>(head_httpd_startup_server_com) for further information on startup
support for these configurations.

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

<HEAD>([Service]\head_virtual_service)

<P> Using the [Service] HTTPD$CONFIG 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
<QUOTE>(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
<REFERENCE>(head_httpd_control)).

<P> This rather contrived example shows a server configured to provide four
services over two host names.

<CODE_EXAMPLE>
  [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
<ENDCODE_EXAMPLE>

<P> Note that both the HTTPD$SERVICE configuration file (see
<REFERENCE>(chapter_service_directives) and the /SERVICE= command-line
qualifier (see <REFERENCE>(head_httpd_command_line)) override this directive.

<HEAD>(HTTPD$SERVICE\head_virtual_httpd_service)

<P> If the logical name HTTPD$SERVICE is defined (and it is optional) the
HTTPD$CONFIG [Service] directive is not used.  As mentioned, this configuration
file is optional.  For simple  sites, those containing one or two services, the
use of a separate service configuration file is probably not warranted.  Once
the number begins to grow this file offers an easier-to-manage interface for
those services.

<P> See <REFERENCE>(chapter_service_directives) for further detail.

<HEAD>([[virtual-server]]\head_virtual_rules)

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

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

<CODE_EXAMPLE>
  # 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
<ENDCODE_EXAMPLE>

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

<HEAD>(Unknown Virtual Server\head_virtual_unknown)

<P> If a service is not configured for the particular host address and port of
a request one of two actions will be taken.

<LIST>(NUMBERED)

<LE> If the configuration directive [ServiceNotFoundURL] is set the request
will be redirected to the specified URL.  This should contain a specific host
name, as well as message page.  For the default page use:

<CODE_EXAMPLE>
  [ServiceNotFoundURL]  //server.host.name/httpd/-/servicenotfound.html
<ENDCODE_EXAMPLE>

<LE> If the above directive is not set the request is mapped using the default
rules (e.g. [[*]]).  It is possible to specify a rule set containing a default
rule for each virtual server.  The unmatched request is then handled by a
fallback rule, as illustrated in the following.

<CODE_EXAMPLE>
  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
<ENDCODE_EXAMPLE>

<ENDLIST>

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

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

<COMMENT>(....................................................................)

<HEAD1>(Error Reporting\head_error_reporting)

<P> By default the server provides it's own internal error reporting facility.
These reports may be configured as <EMPHASIS>(basic) or <EMPHASIS>(detailed) on
a per-path basis, as well as determining the basic <QUOTE>(look-and-feel).  For
more demanding requirements the [ErrorReportPath] configuration directive
allows a redirection path to be specified for error reporting, permitting 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.  Generally an SSI document would be recommended for
it's simplicity yet versatility.

<HEAD2>(Basic and Detailed\head_error_reporting_basic)

<P> Internally generated error reports are the most efficient.  These can be
delivered with two levels of error information.  The default is more detailed.

<COMMENT>(HTML=
<BLOCKQUOTE>
<FONT SIZE=+1>
<B>ERROR 404</B> &nbsp;-&nbsp; The requested resource could not be found.
</FONT>
<BR>Document not found &nbsp;...&nbsp; /ht_root/index.html
<!-- sts: %X00018292 "HT_ROOT:[000000]INDEX.HTML" -->
<BR><I>(document, bookmark, or reference requires revision)</I> 
<BR>Additional information:&nbsp;
<A HREF="/httpd/-/status1xx.html">1<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/status2xx.html">2<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/status3xx.html">3<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/status4xx.html">4<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/status5xx.html">5<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/statushelp.html">Help</A>
<BR><HR WIDTH=85% ALIGN=left SIZE=2 NOSHADE>
<ADDRESS>WASD/7.0.0 Server at <A HREF="mailto:mark.daniel@wasd.vsm.com.au">wasd.dsto.defence.gov.au</A> Port 80</ADDRESS>
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
<CODE_EXAMPLE>
  <EMPHASIS>(ERROR 404\BOLD) - The requested resource could not be found.
  Document not found ... /ht_root/index.html
  <EMPHASIS>((document, bookmark, or reference requires revision))
  Additional information: 1<EMPHASIS>(xx), 2<EMPHASIS>(xx), 3<EMPHASIS>(xx), 4<EMPHASIS>(xx), 5<EMPHASIS>(xx), Help
  -----------------------------------------------------------------
  <EMPHASIS>(WASD/7.0.0 Server at wasd.dsto.defence.gov.au Port 80)
<ENDCODE_EXAMPLE>
<COMMENT>(HTML/ON)

<P> There is also the more basic.

<COMMENT>(HTML=
<BLOCKQUOTE>
<FONT SIZE=+1>
<B>ERROR 404</B> &nbsp;-&nbsp; The requested resource could not be found.
</FONT>
<BR>Additional information:&nbsp;
<A HREF="/httpd/-/status1xx.html">1<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/status2xx.html">2<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/status3xx.html">3<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/status4xx.html">4<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/status5xx.html">5<I>xx</I></A>,&nbsp;
<A HREF="/httpd/-/statushelp.html">Help</A>
<BR><HR WIDTH=85% ALIGN=left SIZE=2 NOSHADE>
<ADDRESS>WASD/7.0.0 Server at <A HREF="mailto:mark.daniel@wasd.vsm.com.au">wasd.dsto.defence.gov.au</A> Port 80</ADDRESS>
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
<CODE_EXAMPLE>
  <EMPHASIS>(ERROR 404\BOLD) - The requested resource could not be found.
  Additional information: 1<EMPHASIS>(xx), 2<EMPHASIS>(xx), 3<EMPHASIS>(xx), 4<EMPHASIS>(xx), 5<EMPHASIS>(xx), Help
  -----------------------------------------------------------------
  <EMPHASIS>(WASD/7.0.0 Server at wasd.dsto.defence.gov.au Port 80)
<ENDCODE_EXAMPLE>
<COMMENT>(HTML/ON)

<P> These can be set per-server using the [ReportBasicOnly] configuration
directive, or on a per-path basis in the HTTPD$MAP configuration file. The
basic report is intended for environments where traditionally a minimum of
information might be provided to the user community, both to reduce site
configuration information leakage but also where a general user population may
only need or want the information that a document was either found or not found.
The detailed report often provides far more specific information as to the
nature of the event and so may be more appropriate to a more technical group of
users.  Either way it is relatively simple to provide one as the default and
the other for specific audiences.  Note that the detailed report also includes
in page <LITERAL>(<META>) information the code module and line references for
reported errors.

<P> To default to a basic report for all but selected resource paths introduce
the following to the top of the HTTPD$MAP configuration file.

<CODE_EXAMPLE>
  # default is basic reports
  set /* report=basic
  set /internal-documents/* report=detailed
  set /other/path/* report=detailed
<ENDCODE_EXAMPLE>

<P> To provide the converse, default to a detailed report for all but selected
paths use the following.

<CODE_EXAMPLE>
  # default is detailed reports
  set /web/* report=basic
<ENDCODE_EXAMPLE>

<HEAD>(Other Customization\head_error_reporting_other)

<P> The additional reference information included in the report may be disabled
using the appropriate HTTPD$MSG [status] message item.  Emptying this message
results in an error report similar to the following.

<COMMENT>(HTML=
<BLOCKQUOTE>
<FONT SIZE=+1>
<B>ERROR 404</B> &nbsp;-&nbsp; The requested resource could not be found.
</FONT>
<BR><HR WIDTH=85% ALIGN=left SIZE=2 NOSHADE>
<ADDRESS>WASD/7.0.0 Server at <A HREF="mailto:mark.daniel@wasd.vsm.com.au">wasd.dsto.defence.gov.au</A> Port 80</ADDRESS>
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
<CODE_EXAMPLE>
  <EMPHASIS>(ERROR 404\BOLD) - The requested resource could not be found.
  -----------------------------------------------------------------
  <EMPHASIS>(WASD/7.0.0 Server at wasd.dsto.defence.gov.au Port 80)
<ENDCODE_EXAMPLE>
<COMMENT>(HTML/ON)

<P> The server signature may be disabled using the HTTPD$CONFIG
[ServerSignature] configuration directive.  This results in a minimal error
report.

<COMMENT>(HTML=
<BLOCKQUOTE>
<FONT SIZE=+1>
<B>ERROR 404</B> &nbsp;-&nbsp; The requested resource could not be found.
</FONT>
</BLOCKQUOTE>
)

<P> A simple approach to providing a site-specific <QUOTE>(look-and-feel) to
server reports is to customize the [ServerReportBodyTag] HTTPD$CONFIG
configuration directive.  Using this directive report page background colour,
background image, text and link colours, etc., may be specified for all
reports.  It is also possible to more significantly change the report format
and contents (within some constraints), without resorting to the site-specific
mechansims refered to below, by changing the contents of the appropriate
HTTPD$MSG [status] item.  This should be undertaken with care. 

<COMMENT>(HTML/OFF)
<CODE_EXAMPLE>
  <EMPHASIS>(ERROR 404\BOLD) - The requested resource could not be found.
<ENDCODE_EXAMPLE>
<COMMENT>(HTML/ON)

<HEAD2>(Site Specific\head_error_reporting_site)

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

<HEAD>(Using an SSI Document\head_error_reporting_ssi)

<P> Three example SSI error report documents are provided.

<COMMENT>(HTML=
<OL>

<LI>
<A HREF="/ht_root/example/reporterror1.shtml?httpd=content&type=text/plain">
HT_ROOT:[EXAMPLE]REPORTERROR1.SHTML</A>
<BR>Provides a report identical with those internally generated in versions
prior to v7.0.

<P>
<LI>
<A HREF="/ht_root/example/reporterror2.shtml?httpd=content&type=text/plain">
HT_ROOT:[EXAMPLE]REPORTERROR2.SHTML</A>
<BR>This is a minor variation, showing how the format may be easily customized.

<P>
<LI>
<A HREF="/ht_root/example/reporterror3.shtml?httpd=content&type=text/plain">
HT_ROOT:[EXAMPLE]REPORTERROR3.SHTML</A>
<BR>This version has a radically different format and content, with much less
specific error information (which some administrator's may consider
advantageous).
  When generated these reports
<A HREF="/ht_root/example/reporterror3.html">look something like this</A>.

<P>
<LI>
<A HREF="/ht_root/example/reporterror4.shtml?httpd=content&type=text/plain">
HT_ROOT:[EXAMPLE]REPORTERROR4.SHTML</A>
<BR> This example uses the report format provided with WASD v7.0 and later,
and <A HREF="/ht_root/example/reporterror4.html">look something like this</A>.

<P>
<LI>
<A HREF="/ht_root/example/reporterror5.shtml?httpd=content&type=text/plain">
HT_ROOT:[EXAMPLE]REPORTERROR5.SHTML</A>
<BR>This is another variation, showing how the format may be easily customized.
When generated this report <A HREF="/ht_root/example/reporterror5.html">looks
something like this</A>.

</OL>
)

<COMMENT>(HTML/OFF)
See HT_ROOT:[EXAMPLE]REPORTERROR*.SHTML
The first providing a report identical with those internally generated, the
second a small variation on this, and the third considerably different and with
much less specific error information (which some administrator's may consider
advantageous).
<COMMENT>(HTML/ON)

<P> 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

<CODE_EXAMPLE>
  [ErrorReportPath] /ht_root/local/reporterror.shtml
<ENDCODE_EXAMPLE>

<P> 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. For instance the following arrangement provides each host (service)
with an customized error report.

<CODE_EXAMPLE>
  # HTTPD$CONFIG
  [ErrorReportPath] /errorreport.shtml

  # HTTPD$MAP
  [[alpha.wasd.dsto.gov.au]]
  pass /errorreport.shtml /ht_root/local/alphareport.shtml
  [[beta.wasd.dsto.gov.au]]
  pass /errorreport.shtml /ht_root/local/betareport.shtml
  [[gamma.wasd.dsto.gov.au]]
  pass /errorreport.shtml /ht_root/local/gammareport.shtml
<ENDCODE_EXAMPLE>

<P> The following SSI variables are available specifically for generating
error reports. The <LITERAL>(<!--#printenv -->) statement near the top of the
file may be uncommented to view all SSI and CGI variables available.

<LIST>(unnumbered)

<LE> <EMPHASIS>(ERROR_LINE - \BOLD)
The HTTPd source code line from where the error was generated.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_MODULE - \BOLD)
The HTTPd source code module corresponding to the line described above.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_REPORT - \BOLD)
A single HTML string providing a detailed error message.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_REPORT2 - \BOLD)
A single HTML comment providing more detailed VMS error information (if
available).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_REPORT3 - \BOLD)
A server-generated HTML string providing a brief explanation of the error (if
available).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_STATUS_CLASS - \BOLD)
Essentially the single hundreds digit from the status code (e.g. 4).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_STATUS_CODE - \BOLD)
The HTTP response status code representing the error (e.g. 404).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_STATUS_EXPLANATION - \BOLD)
The HTTP response status code descriptive meaning (e.g. <QUOTE>(The requested
resource could not be found.)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_STATUS_TEXT - \BOLD)
The HTTP response status code abbreviated meaning (e.g. <QUOTE>(Not Found)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERROR_STATUS_TYPE - \BOLD)
<QUOTE>(basic) or <QUOTE>(detailed).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FORM_ERROR_<HELLIPSIS> - \BOLD)
A series of CGI variables providing the sources for the above SSI variables, as
well as other general environment information.

<ENDLIST>

<P> Once the SSI report document has been satifactorily developed and is to be
put into production it is recommended it be <EMPHASIS>(SCRUNCHED\BOLD), making
it's processing significantly more efficient.  See <REFERENCE>(head_scrunch).

<HEAD>(Using a Script\head_error_reporting_script)

<P> 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

<COMMENT>(HTML=
<A HREF="/ht_root/src/misc/reporterror.c">HT_ROOT:[SRC.MISC]REPORTERROR.C</A>
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.MISC]REPORTERROR.C
<COMMENT>(HTML/ON)

provides such an implementation example.

<HEAD>(Using HTML Documents\head_error_reporting_html)

<P> 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 <QUOTE>(!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.

<CODE_EXAMPLE>
  [ErrorReportPath] /ht_root/local/reporterror!UL.html
<ENDCODE_EXAMPLE>

<P> This mapping will generate paths such as the following, and require at
least these to respond to general errors.

<CODE_EXAMPLE>
  /ht_root/local/reporterror400.html
  /ht_root/local/reporterror401.html
  /ht_root/local/reporterror403.html
  /ht_root/local/reporterror404.html
  /ht_root/local/reporterror409.html
  /ht_root/local/reporterror500.html
  /ht_root/local/reporterror501.html
  /ht_root/local/reporterror502.html
  /ht_root/local/reporterror503.html
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<HEAD1>(Access Logging\head_access_logging)

<P> WASD provides a versatile access log, allowing data to be collected in
Web-standard <EMPHASIS>(common) and <EMPHASIS>(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.

<HEAD2>(Log Format\head_log_format)

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

<LIST>(NUMBERED)                

<LE> <EMPHASIS>(COMMON -\BOLD)
This is the most common, base logging format for Web servers.  COMMON is the
default log format.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(COMMON_SERVER -\BOLD)
This is an optional format used, for one, by the NCSA server.  It is basically
the common format, with the server host name appended to the line (used for
multi-homed servers, see <REFERENCE>(head_virtual_services)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(COMBINED -\BOLD)
This is an optional format used, for one again, by the NCSA server.  It too is
basically the common format, with the HTTP referer and user agent appended.

<ENDLIST>

<HEAD>(User-Defined\head_log_user_defined)

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

<P> Two different "escape" characters introduce the following parameters:

<P><LINE> A <QUOTE>(!) followed by

<LIST>(UNNUMBERED)
<LE><EMPHASIS>(AR -\BOLD) authentication realm (if any)
<LE><EMPHASIS>(AU -\BOLD) authenticated user name (if any)
<LE><EMPHASIS>(BB -\BOLD) bytes in body (excludes response header)
<LE><EMPHASIS>(BY -\BOLD) bytes in response (includes header)
<LE><EMPHASIS>(CA -\BOLD) client address
<LE><EMPHASIS>(CN -\BOLD) client host name (or address if DNS lookup disabled)
<LE><EMPHASIS>(EM -\BOLD) request elapsed time in milliseconds
<LE><EMPHASIS>(ES -\BOLD) request elapsed time in fractional seconds
<LE><EMPHASIS>(ID -\BOLD) session track ID
<LE><EMPHASIS>(ME -\BOLD) request method
<LE><EMPHASIS>(PA -\BOLD) request path (not to be confused with <QUOTE>(RQ))
<LE><EMPHASIS>(QS -\BOLD) request query string (if any)
<LE><EMPHASIS>(RF -\BOLD) referer (if any)
<LE><EMPHASIS>(RQ -\BOLD) complete request string (see below)
<LE><EMPHASIS>(RS -\BOLD) response status code
<LE><EMPHASIS>(SN -\BOLD) server host name
<LE><EMPHASIS>(SC -\BOLD) script name (if any)
<LE><EMPHASIS>(SM -\BOLD) request scheme (http: or https:)
<LE><EMPHASIS>(SP -\BOLD) server port
<LE><EMPHASIS>(TC -\BOLD) request time (common log format)
<LE><EMPHASIS>(TG -\BOLD) request time (GMT)
<LE><EMPHASIS>(TV -\BOLD) request time (VMS format)
<LE><EMPHASIS>(UA -\BOLD) user agent
<ENDLIST>

<P><LINE> A <QUOTE>(<BACKSLASH>) followed by

<LIST>(UNNUMBERED)
<LE><EMPHASIS>(0 -\BOLD) a null character (used to define the empty field character)
<LE><EMPHASIS>(! -\BOLD) insert an <QUOTE>(!)
<LE><EMPHASIS>(<BACKSLASH> -\BOLD) insert a <QUOTE>(<BACKSLASH>)
<LE><EMPHASIS>(n -\BOLD) insert a newline
<LE><EMPHASIS>(q -\BOLD) insert a quote (so that in DCL the quotes won't need escaping!)
<LE><EMPHASIS>(t -\BOLD) insert a TAB
<ENDLIST>

<P><LINE> Any other character is directly inserted into the log entry.

<HEAD>(Note on <QUOTE>(PA) and <QUOTE>(RQ)\log_format_note)

<P> The <QUOTE>(PA) and <QUOTE>(RQ) have distinct roles.  In general the
<QUOTE>(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 <QUOTE>(PA) directive is merely the path string after
any script and query string components have been removed.

<HEAD>(Examples\log_format_examples)

<LIST>(NUMBERED)

<LE> The equivalent of the common log format is:

<CODE_EXAMPLE>
  -!CN - !AU [!TC] \q!RQ\q !RS !BY
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The combined log format could be specified as:

<CODE_EXAMPLE>
  -!CN - !AU [!TC] \q!RQ\q !RS !BY \q!RF\q \q!UA\q
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The <EMPHASIS>(O'Reilly WebSite) <QUOTE>(windows log format) would be
created by:

<CODE_EXAMPLE>
  \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
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The common log format with appended request duration in seconds could be
provided using:

<CODE_EXAMPLE>
  -!CN - !AU [!TC] \q!RQ\q !RS !BY !ES
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(....................................................................)

<HEAD2>(Log Period\head_log_period)

<P> 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

<LIST>(UNNUMBERED)

<LE> DAILY

<COMMENT>(HTML=<P>)

<LE> weekly as <HELLIPSIS>
<LINE> MONDAY
<LINE> TUESDAY
<LINE> WEDNESDAY
<LINE> THURSDAY
<LINE> FRIDAY
<LINE> SATURDAY
<LINE> SUNDAY

<COMMENT>(HTML=<P>)

<LE> MONTHLY

<ENDLIST>

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

<P> 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

<LIST>(UNNUMBERED)
<LE> server host name
<LE> server port
<LE> year (YYYY)
<LE> month (MM)
<LE> day (DD)
<ENDLIST>

<CP> as in the following example

<CODE_EXAMPLE>
  HT_LOGS:WASD_80_19971013_ACCESS.LOG
<ENDCODE_EXAMPLE>

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

<COMMENT>(....................................................................)

<HEAD2>(Log Per-Service\head_log_per_service)

<P> 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 <REFERENCE>(head_virtual_services)).
The [LogNaming] format can be any of "NAME" (default) which names the log file
using the first period-delimited component of the IP host name, "HOST" which
uses as much of the IP host name as can be accomodated within the maximum 39
character filename limitation (of ODS-2), or "ADDRESS" which uses the full IP
host address in the name.  Both HOST and ADDRESS have hyphens substituted for
periods in the string.  If these are specified then by default the service port
follows the host name component.  This may be suppressed using the
[LogPerServiceHostOnly] directive, allowing a minimum extra 3 characters in the
name, and combining entries for all ports associated with the host name
(for example, a standard HTTP service on port 80 and an SSL service on port 443
would have entries in the  one file).

<COMMENT>(....................................................................)

<HEAD2>(Log Naming\head_log_naming)

<P> 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:

<LIST>(UNNUMBERED)                
<LE> ADDRESS
<LE> HOST
<LE> NAME (default)
<ENDLIST>

<P> Examples of generated per-service (non-per-period) log names:

<CODE_EXAMPLE>
  HT_LOGS:131-185-250-202_80_ACCESS.LOG
  HT_LOGS:WASD-DSTO-DEFENCE-GOV-AU_80_ACCESS.LOG
  HT_LOGS:WASD_80_ACCESS.LOG
<ENDCODE_EXAMPLE>

<P> Examples of generated per-period (with/without per-service) log names:

<CODE_EXAMPLE>
  HT_LOGS:131-185-250-202_80_19971013_ACCESS.LOG
  HT_LOGS:WASD-DSTO-DEFENCE-GO_80_19971013_ACCESS.LOG
  HT_LOGS:WASD_80_19971013_ACCESS.LOG
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<HEAD2>(Access Tracking\head_log_tracking)

<P> The term <EMPHASIS>(access tracking) describes the ability to follow a
single user's accesses through a particular site or group of related sites. 
This is accomplished by setting a unique cookie in a user's browser.  This
cookie is then sent with all requests to that site.  The site detects the
cookie's unique identifier, or token, and includes it the access log, allowing
the user's route through the site or sites to be reviewed.  Note that a browser 
must have cookies enabled for this mechanism to operate.  

<P> WASD access tracking is controlled using the [Track...] directives.  The
tracking cookie uses an opaque, nineteen character string as the token (e.g.
<QUOTE>(ORoKJAOef8sAAAkuACc)).  This token is spatially and temporally
completely unique, generated the first time a user's browser accesses the site. 
This token is by default added to the server access log in the common format
<QUOTE>(remote-ID) location.  It can also be placed into custom logs.  From
this identifier in the logs a session's progress may be easily tracked. 
<EMPHASIS>(Note that the token contains nothing related to the user's actual
identity!\BOLD)  It is merely a unique identifier that tags a single browser's
access trail through a site. 

<P> The [Track] directive enables access tracking on a per-server basis.  By
default all non-proxy services will then have tracking enabled.  Individual
services may be then be disabled (or enabled in the case of proxy services)
using the per-service <QUOTE>(;notrack) and <quote>(;track) parameters.

<P> By default a session track token expires when the user closes the browser. 
To encourage the browser to keep this token between uses enable multi-session
tracking using the [TrackMultiSession] directive.  Note that browsers may
dispose of any cookie at any time resources become scarce, and that users can
also remove them.

<P> Session tracking can be extended from the default of the local server
(virtual if applicable) to a group of servers within a local domain.  This
means the same, initial identifier appears in the logs of all WASD servers in a
related group of hosts.  Of course tracking must be enabled on all servers. 
The host grouping is specified using the [TrackDomain] directive (this follows
the general rules governing cookie domain behaviour - see RFC2109).  Most host
grouping require <EMPHASIS>(a minimum of three dots\BOLD) in the specification. 
For example (note the leading dot)

<CODE_EXAMPLE>
  .site.org.domain
<ENDCODE_EXAMPLE>

<P> which would match the following servers, <QUOTE>(curly.site.org.domain),
<QUOTE>(larry.site.org.domain), <QUOTE>(moe.site.org.domain), etc.  Sites in
top-level domains (e.g. <QUOTE>(edu), <QUOTE>(com), <QUOTE>(org)) need only
specify a minimum of two periods.

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Server Configuration Directives\chapter_config_directives)

<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 <REFERENCE>(chapter_server_admin)).  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.

<COMMENT>(....................................................................)

<COMMENT>(HTML=
The example
<A HREF="/ht_root/example/httpd$config.conf">configuration file</A> can be used
as a template.
)

<COMMENT>(HTML/OFF)
The example configuration file can be used as a template.
<P><BOX>(online hypertext link)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)
<ENDNOTE>

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

<P> Note that all <EMPHASIS>(boolean) directives are <EMPHASIS>(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
<EMPHASIS>(must\BOLD) be explicitly enabled.

<HEAD1>(Functional Groupings\head_config_directives_func)

<P>
<CENTER_LINE>(<EMPHASIS>(Authentication/Authorization\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([AuthBasic]\BOLD)\enable BASIC method)
<TABLE_ROW>(<EMPHASIS>([AuthCacheMinutes]\BOLD)\minutes before explicitly
reauthorizing user from sources)
<TABLE_ROW>(<EMPHASIS>([AuthDigest]\BOLD)\enable DIGEST method)
<TABLE_ROW>(<EMPHASIS>([AuthDigestGetLife]\BOLD)\DIGEST method GET lifetime)
<TABLE_ROW>(<EMPHASIS>([AuthDigestPutLife]\BOLD)\DIGEST method PUT lifetime)
<TABLE_ROW>(<EMPHASIS>([AuthFailureLimit]\BOLD)\retries allowed before username
is marked as intruder)
<TABLE_ROW>(<EMPHASIS>([AuthRevalidateLoginCookie]\BOLD)\helps prevent
redundant authorization requests when user revalidation is enabled)
<TABLE_ROW>(<EMPHASIS>([AuthRevalidateUserMinutes]\BOLD)\minutes before use
needs to reenter password)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Buffer Sizes\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([BufferSizeDclCgiPlusIn]\BOLD)\number of bytes allocated
to scripting subprocess CGIPLUSIN mailbox)
<TABLE_ROW>(<EMPHASIS>([BufferSizeDclCommand]\BOLD)\bytes allocated to
scripting subprocess SYS$COMMAND mailbox)
<TABLE_ROW>(<EMPHASIS>([BufferSizeDclOutput]\BOLD)\bytes allocated to scripting
subprocess SYS$OUTPUT mailbox)
<TABLE_ROW>(<EMPHASIS>([BufferSizeNetRead]\BOLD)\bytes allocated to client
request read buffer, and to the scripting subprocess SYS$INPUT mailbox)
<TABLE_ROW>(<EMPHASIS>([BufferSizeNetWrite]\BOLD)\bytes allocated to client
output buffer)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Directory Listing\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([AddIcon]\BOLD)\path to icon for a specified
content-type)
<TABLE_ROW>(<EMPHASIS>([AddBlankIcon]\BOLD)\path to blank icon)
<TABLE_ROW>(<EMPHASIS>([AddDirIcon]\BOLD)\path to directory icon)
<TABLE_ROW>(<EMPHASIS>([AddParentIcon]\BOLD)\path to parent icon)
<TABLE_ROW>(<EMPHASIS>([AddUnknownIcon]\BOLD)\path to icon for unknown
content-type)
<TABLE_ROW>(<EMPHASIS>([DirAccess]\BOLD)\enable and form of listing)
<TABLE_ROW>(<EMPHASIS>([DirBodyTag]\BOLD)\specify HTML body tag of listing
pages)
<TABLE_ROW>(<EMPHASIS>([DirDescriptionLines]\BOLD)\number of HTML file lines
searched for document title)
<TABLE_ROW>(<EMPHASIS>([DirLayout]\BOLD)\layout of the various listing
components)
<TABLE_ROW>(<EMPHASIS>([DirMetaInfo]\BOLD)\add server and VMS directory
information)
<TABLE_ROW>(<EMPHASIS>([DirNoImpliedWildcard]\BOLD)\do not add wildcards to
request if not present in path)
<TABLE_ROW>(<EMPHASIS>([DirNoPrivIgnore]\BOLD)\ignore, do not report, 
privilege violations on files/directories)
<TABLE_ROW>(<EMPHASIS>([DirOwner]\BOLD)\allow owner of file to be included in
layout directive)
<TABLE_ROW>(<EMPHASIS>([DirPreExpired]\BOLD)\pre-expire listing responses)
<TABLE_ROW>(<EMPHASIS>([DirReadMeFile]\BOLD)\specify read-me files)
<TABLE_ROW>(<EMPHASIS>([DirWildcard]\BOLD)\allow wildcards to be specified at
all)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(File Cache\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([CacheChunkKBytes]\BOLD)\memory block allocation size)
<TABLE_ROW>(<EMPHASIS>([CacheEntriesMax]\BOLD)\maximum number of files allowed
in cache)
<TABLE_ROW>(<EMPHASIS>([CacheFileKBytesMax]\BOLD)\maximum size of a file)
<TABLE_ROW>(<EMPHASIS>([CacheFrequentHits]\BOLD)\identify active files)
<TABLE_ROW>(<EMPHASIS>([CacheFrequentSeconds]\BOLD)\identify active file)
<TABLE_ROW>(<EMPHASIS>([CacheHashTableEntries]\BOLD)\size of hash table)
<TABLE_ROW>(<EMPHASIS>([CacheTotalKBytesMax]\BOLD)\maximum memory to be
consumed by cache)
<TABLE_ROW>(<EMPHASIS>([CacheValidateSeconds]\BOLD)\maximum period before the
cache checks for file modification)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Logging\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([Logging]\BOLD)\enable logging)
<TABLE_ROW>(<EMPHASIS>([LogExcludeHosts]\BOLD)\hosts to be excluded from log)
<TABLE_ROW>(<EMPHASIS>([LogFormat]\BOLD)\nature and layout of log contents)
<TABLE_ROW>(<EMPHASIS>([LogNaming]\BOLD)\how the log name is be constructed)
<TABLE_ROW>(<EMPHASIS>([LogPeriod]\BOLD)\period at which new logs are created)
<TABLE_ROW>(<EMPHASIS>([LogPerService]\BOLD)\create a separate log for each
configured service)
<TABLE_ROW>(<EMPHASIS>([LogPerServiceHostOnly]\BOLD)\suppress service port
number as component of log name)
<TABLE_ROW>(<EMPHASIS>([Track]\BOLD)\enable session tracking)
<TABLE_ROW>(<EMPHASIS>([TrackMultiSession]\BOLD)\track across sessions)
<TABLE_ROW>(<EMPHASIS>([TrackDomain]\BOLD)\host or hosts it applies to)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Operator Console and Log\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([OpcomAdmin]\BOLD)\server administration menu directives)
<TABLE_ROW>(<EMPHASIS>([OpcomAuthorization]\BOLD)\authentication/authorization
messages, e.g. failures)
<TABLE_ROW>(<EMPHASIS>([OpcomControl]\BOLD)\CLI HTTPd control directives)
<TABLE_ROW>(<EMPHASIS>([OpcomHTTPd]\BOLD)\HTTPd events, e.g. startup, exit)
<TABLE_ROW>(<EMPHASIS>([OpcomProxyMaint]\BOLD)\proxy file cache maintenance)
<TABLE_ROW>(<EMPHASIS>([OpcomTarget]\BOLD)\target operator for online messages)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Miscellaneous\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<COMMENT>(HTML=<TR></TR>)
<TABLE_ROW>(<EMPHASIS>([Accept]\BOLD)\restrictive list of host from which to
accept requests)
<TABLE_ROW>(<EMPHASIS>([ActivityDays]\BOLD)\activity graph duration)
<TABLE_ROW>(<EMPHASIS>([AddType]\BOLD)\add a content-type)
<TABLE_ROW>(<EMPHASIS>([Busy]\BOLD)\number of concurrent connections allowed)
<TABLE_ROW>(<EMPHASIS>([CharsetDefault]\BOLD)\default character set for text
responses)
<TABLE_ROW>(<EMPHASIS>([DNSLookup]\BOLD)\enable host lookup)
<TABLE_ROW>(<EMPHASIS>([Monitor]\BOLD)\enable HTTPDMON data logicals)
<TABLE_ROW>(<EMPHASIS>([Port]\BOLD)\default port)
<TABLE_ROW>(<EMPHASIS>([PutMaxKBytes]\BOLD)\maximum size of a POST or PUT)
<TABLE_ROW>(<EMPHASIS>([PutVersionLimit]\BOLD)\maximum RMS file versions
retained in a POST or PUT)
<TABLE_ROW>(<EMPHASIS>([Reject]\BOLD)\proscriptive list of hosts from which
request will be rejected)
<TABLE_ROW>(<EMPHASIS>([RequestHistory]\BOLD)\number of requests kept for
request report)
<TABLE_ROW>(<EMPHASIS>([SearchScript]\BOLD)\path to default search script)
<TABLE_ROW>(<EMPHASIS>([SearchScriptExclude]\BOLD)\list of file extensions
excluded from implied keyword search)
<TABLE_ROW>(<EMPHASIS>([Service]\BOLD)\list of host names and/or port to create
services for)
<TABLE_ROW>(<EMPHASIS>([ServiceNotFoundURL]\BOLD)\redirection URL when a
request service is not configured)
<TABLE_ROW>(<EMPHASIS>([StreamLF]\BOLD)\enable and set maximum size of
automatic Stream-LF conversion)
<TABLE_ROW>(<EMPHASIS>([Welcome]\BOLD)\list of file names that are checked for
as home pages)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Proxy Serving\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([ProxyCache]\BOLD)\enable proxy caching)
<TABLE_ROW>(<EMPHASIS>([ProxyCacheFileKBytesMax]\BOLD)\maximum size of response
for caching)
<TABLE_ROW>(<EMPHASIS>([ProxyCacheRoutineHourOfDay]\BOLD)\hour of day routine
cache purge occurs)
<TABLE_ROW>(<EMPHASIS>([ProxyCacheDeviceCheckMinutes]\BOLD)\minutes between
check of cache device usage)
<TABLE_ROW>(<EMPHASIS>([ProxyCacheDeviceDirOrg]\BOLD)\flat 256 or 64x64
directory organization)
<TABLE_ROW>(<EMPHASIS>([ProxyCacheDeviceMaxPercent]\BOLD)\maximum percentage of
cache device used before purge)
<TABLE_ROW>(<EMPHASIS>([ProxyCacheDevicePurgePercent]\BOLD)\during purge reduce
by this many percent)
<TABLE_ROW>(<EMPHASIS>([ProxyCachePurgeList]\BOLD)\list of file ages used
during purge)
<TABLE_ROW>(<EMPHASIS>([ProxyCacheReloadList]\BOLD)\list of file ages before
realod from source)
<TABLE_ROW>(<EMPHASIS>([ProxyForwardedBy]\BOLD)\add <QUOTE>(Forwarded-by) to
requests)
<TABLE_ROW>(<EMPHASIS>([ProxyHostCachePurgeHours]\BOLD)\period at which DNS
information is purged)
<TABLE_ROW>(<EMPHASIS>([ProxyHostLookupRetryCount]\BOLD)\DNS resolution retry
count)
<TABLE_ROW>(<EMPHASIS>([ProxyReportLog]\BOLD)\report failures to process log)
<TABLE_ROW>(<EMPHASIS>([ProxyReportCacheLog]\BOLD)\report cache failures to
process log)
<TABLE_ROW>(<EMPHASIS>([ProxyServing]\BOLD)\enable proxy server)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Reports\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<COMMENT>(HTML=<TR></TR>)
<TABLE_ROW>(<EMPHASIS>([ErrorReportPath]\BOLD)\path to script, SSI or
<QUOTE>(flat) error document) 
<TABLE_ROW>(<EMPHASIS>([ErrorRecommend]\BOLD)\for server generated error
include probable cause)
<TABLE_ROW>(<EMPHASIS>([ReportBasicOnly]\BOLD)\only ever generate reports
containing basic details)
<TABLE_ROW>(<EMPHASIS>([ReportMetaInfo]\BOLD)\add server information to
directory listings, etc.)
<TABLE_ROW>(<EMPHASIS>([ServerAdmin]\BOLD)\email address for server-related
contact)
<TABLE_ROW>(<EMPHASIS>([ServerAdminBodyTag]\BOLD)\specify HTML body tag of
server administration (menu) pages)
<TABLE_ROW>(<EMPHASIS>([ServerReportBodyTag]\BOLD)\specify HTML body tag of
error and other report pages)
<TABLE_ROW>(<EMPHASIS>([ServerSignature]\BOLD)\add server information to the
foot of error and other report pages)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Request Timeout\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([TimeoutInput]\BOLD)\minutes a connection can wait
before sending request)
<TABLE_ROW>(<EMPHASIS>([TimeoutKeepAlive]\BOLD)\seconds a connection is kept
active after request conclusion)
<TABLE_ROW>(<EMPHASIS>([TimeoutOutput]\BOLD)\minutes a response can continue to
output)
<TABLE_ROW>(<EMPHASIS>([TimeoutNoProgress]\BOLD)\minutes a response can
continue without data transfer progress)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Scripting\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([CgiStrictOutput]\BOLD)\script output must be CGI
compliant)
<TABLE_ROW>(<EMPHASIS>([DclCgiPlusLifeTime]\BOLD)\minutes of non-use before
CGIplus subprocess is deleted)
<TABLE_ROW>(<EMPHASIS>([DclCleanupScratchMinutesMax]\BOLD)\maximum minutes
between HT_SCRATCH cleanups)
<TABLE_ROW>(<EMPHASIS>([DclCleanupScratchMinutesOld]\BOLD)\cleanup files older
than this)
<TABLE_ROW>(<EMPHASIS>([DclDetachProcess]\BOLD)\use detached scripting
processes rather than subprocesses) 
<TABLE_ROW>(<EMPHASIS>([DclGatewayBG]\BOLD)\enable raw TCP/IP socket for
scripts) 
<TABLE_ROW>(<EMPHASIS>([DclHardLimit]\BOLD)\maximum number of concurrent
subprocesses)
<TABLE_ROW>(<EMPHASIS>([DclScriptRunTime]\BOLD)\script execution environment)
<TABLE_ROW>(<EMPHASIS>([DclSoftLimit]\BOLD)\maximum number of subprocesses
before proactive deletion begins)
<TABLE_ROW>(<EMPHASIS>([DclSpawnAuthPriv]\BOLD)\spawn subprocesses with
account's authorized privileges)
<TABLE_ROW>(<EMPHASIS>([DclZombieLifeTime]\BOLD)\minutes of non-use before a
CGI/CLI subprocess is deleted)
<TABLE_ROW>(<EMPHASIS>([DecnetReuseLifeTime]\BOLD)\minutes of non-use before a
DECnet process is released)
<TABLE_ROW>(<EMPHASIS>([DecnetConnectListMax]\BOLD)\maximum number of DECnet
processes)
<TABLE_ROW>(<EMPHASIS>([Scripting]\BOLD)\enables and disables all scripting)
<ENDTABLE>

<P>
<CENTER_LINE>(<EMPHASIS>(Server Side Includes\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([SSI]\BOLD)\enable Server Side Includes (SSI))
<TABLE_ROW>(<EMPHASIS>([SSIaccesses]\BOLD)\allow access counting)
<TABLE_ROW>(<EMPHASIS>([SSIexec]\BOLD)\allow DCL commands)
<ENDTABLE>

<HEAD1>(Alphabetic Listing\head_config_directives_alpha)

<COMMENT>(HTML=<BR>)

<LIST>(NUMBERED)

<LE> <EMPHASIS>([Accept] <EMPHASIS>(host/domain name)\BOLD)
<EMPHASIS>((default: all))

<P> One or more (comma-separated if on the same line) internet host/domain
names, with <QUOTE>(*) 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.

<P> Examples: 

<CODE_EXAMPLE>
  [Accept]
  *.wasd.dsto.defence.gov.au
  131.185.250.*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ActivityDays] <EMPHASIS>(integer)\BOLD) 
<EMPHASIS>((default: 0)) 

<P> Specifies the number of days to record activity statistics, available in
report form from the server administration menu (see
<REFERENCE>(head_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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AddIcon] <EMPHASIS>(icon-URL) <EMPHASIS>(ALT-text) 
<EMPHASIS>(template) \BOLD) 
<EMPHASIS>((no default)) 

<P> Specifies a directory listing icon and alternative text for the mime 
content type specified in the template.

<LINE>(SMALLSKIP) Examples: 

<CODE_EXAMPLE>
  [AddIcon]
  /icon/-/doc.gif    [HTM]  text/html
  /icon/-/text.gif   [TXT]  text/plain
  /icon/-/image.gif  [IMG]  image/gif
<ENDCODE_EXAMPLE>

<LE> <EMPHASIS>([AddBlankIcon] <EMPHASIS>(icon-URL)\BOLD)
<LINE> <EMPHASIS>([AddDirIcon] <EMPHASIS>(icon-URL) <EMPHASIS>(ALT-text)\BOLD)
<LINE> <EMPHASIS>([AddParentIcon] <EMPHASIS>(icon-URL) <EMPHASIS>(ALT-text)\BOLD)
<LINE> <EMPHASIS>([AddUnknownIcon] <EMPHASIS>(icon-URL) <EMPHASIS>(ALT-text)\BOLD)
<EMPHASIS>((no defaults)) 
<LINE>(SMALLSKIP)
Specifies a directory listing icon for these non-content-type parts of the 
listing.
<LINE>(SMALLSKIP)
Examples:

<CODE_EXAMPLE>
  [AddBlankIcon]    /icon/-/blank.gif
  [AddDirIcon]      /icon/-/dir.gif      [DIR]
  [AddParentIcon]   /icon/-/back.gif     <LITERAL>([<--])
  [AddUnknownIcon]  /icon/-/unknown.gif  [???] 
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AddType] <EMPHASIS>(.suffix) <EMPHASIS>(content-type)
<EMPHASIS>(script-name) <EMPHASIS>(description) \BOLD)
<EMPHASIS>((no default)) 

<P> Binds a file suffix (extension, type) to a mime content type.
The script name is used to auto-script against a specified file type.  Use a
hyphen as a place-holder and to indicate no auto-script.  The description is
used as documentation for directory listings. 

<CODE_EXAMPLE>
  [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
<ENDCODE_EXAMPLE>

<P> The content-type string may include a specific character set. In this way
non-default sets (which is usually ISO-8859-1) can be specified for any
particular site or any particular file type. Enclose the content-type string
with double-quotation marks.

<CODE_EXAMPLE>
  [AddType]
  .html    "text/html; charset=ISO-8859-1"   -  HTML (ISO-8859-1)
  .html_5  "text/html; charset=ISO-8859-5"   -  Cyrillic HTML (ISO-8859-5)
  .html_r  "text/html; charset=KOI8-R"       -  Cyrillic HTML (KOI8-R)
  .txt     "text/plain; charset=ISO-8859-1"  -  plain text (ISO-8859-1)
  .txt_5   "text/plain; charset=ISO-8859-5"  -  Cyrillic text (ISO-8859-5)
  .txt_r   "text/plain; charset=KOI8-R"      -  Cyrillic text (KOI8-R)
<ENDCODE_EXAMPLE>

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthBasic] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables BASIC username authentication.  See 
<REFERENCE>(chapter_authorization).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthCacheMinutes] <EMPHASIS>(integer)\BOLD) 
<EMPHASIS>((default: 60)) 

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthDigest] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables Digest username authentication.  See 
<REFERENCE>(chapter_authorization).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthDigestGetLife] <EMPHASIS>(integer)\BOLD) 
<EMPHASIS>((default: 0)) 

<P> The number of seconds a digest nonce for a GET request (read) can be used
before becoming stale.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthDigestPutLife] <EMPHASIS>(integer)\BOLD) 
<EMPHASIS>((default: 0)) 

<P> The number of seconds a digest nonce for a PUT (/POST/DELETE ... write)
request can be used before becoming stale.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthFailureLimit] <EMPHASIS>(integer)\BOLD) 
<EMPHASIS>((default: 10)) 

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthRevalidateLoginCookie] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> When user revalidation is in effect (see immediately below), after having
previously closed the browser initial authentication of a resource is
immediately followed by another if a cached entry on the server indicated
revalidation was required.  This prevents this second request.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthRevalidateUserMinutes] <EMPHASIS>(integer)\BOLD) 
<EMPHASIS>((default: 60)) 

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([BufferSizeDclCgiPlusIn] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 2048))

<P> The number of bytes (and hence BYTLM quota) permanently allocated to each
scripting subprocess CGIPLUSIN mailbox.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([BufferSizeDclCommand] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 3072))

<P> The number of bytes (and hence BYTLM quota) permanently allocated to each
scripting subprocess SYS$COMMAND mailbox.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([BufferSizeDclOutput] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 4096))

<P> The number of bytes (and hence BYTLM quota) permanently allocated to each
scripting subprocess SYS$OUTPUT mailbox.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([BufferSizeNetRead] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 2048))

<P> The number of bytes allocated to the network read buffer (used for request
header, POST body, etc.).  Also the number of bytes (and hence BYTLM quota)
permanently allocated to each scripting subprocess SYS$INPUT mailbox (allowing
a script to read a request body).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([BufferSizeNetWrite] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 4096))

<P> Number of bytes allocated to the network write buffer.  This buffer is used
as the basic unit when transfering file contents (from cache or the file
system), as an output buffer during SSI pocessing, directory listing, etc. 
During many activities multiple outputs are buffered into this storage before
being written to the network.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Busy] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 10))

<P> The maximum number of concurrent client connections before a 
<QUOTE>(<EMPHASIS>(server too busy right now ... try again shortly)) error 
is returned to the client. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Cache] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> File cache control.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CacheChunkKBytes] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> Granularity of memory blocks allocated to file data, in kilobytes.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CacheEntriesMax] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> Maximum number of files loaded into the cache before entries are reused
removing the original contents from the cache.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CacheFileKBytesMax] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> Maximum size of a file before it is not a candidate for being cached, in
kilobytes.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CacheFrequentHits] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> Minimum, total number of hits an entry must sustain before being a
candidate for [CacheFrequentSeconds] assessment.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CacheFrequentSeconds] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> 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 <REFERENCE>(chapter_cache).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CacheHashTableEntries] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> Size of the hash table.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CacheTotalKBytesMax] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> Maximum memory allocated to the cache, in kilobytes.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CacheValidateSeconds] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CharsetDefault] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> The default character set sent in the response header for text documents
(plain and HTML).  English language sites should specify ISO-8859-1, other
Latin alphabet sites, ISO-8859-2, 3, etc. Cyrillic sites might wish to specify
ISO-8859-5 or KOI8-R, and so on.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([CgiStrictOutput]
<EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> A script must output a full HTTP or CGI-compliant response.  If a
plain-text stream is output an error is reported (being the more common
behaviour for servers).  Errors in output can be disagnosed using the WATCH 
facility.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclCleanupScratchMinutesMax] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> Whenever the last scripting process is removed from the system, or this
number of minutes maximum (whichever occurs first), scan the HT_SCRATCH
directory (if logical defined and it exists) deleting all files that are older
than [DclCleanupScratchMinutesOld] minutes.  Setting to zero disables
HT_SCRATCH scans.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclCleanupScratchMinutesOld] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> When performing a [DclCleanupScratchMinutesMax] scan delete files that are
older than this value (or the value specified by [DclCleanupScratchMinutesMax],
whichever is the larger).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclCgiPlusLifeTime] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclDetachProcess]
<EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> By default scripts are executed within server subprocesses.  When enabled
this instructs the server to create detached processes.  This side-steps the
issues of having pooled process quotas and also allows non-server-account
scripting (see <REFERENCE>(head_httpd_command_line),
<REFERENCE>(head_user_scripts) and in particular <QUOTE>(Scripting Overview, 
Introduction).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclDetachProcessPriority] <EMPHASIS>(integer[,integer])\BOLD)
<EMPHASIS>((default: same as server))

<P> When detached scripting processes are created it is possible to assign them
base priorities lower that the server itself.  This directive takes one or two
(comma-separated) integers that determine how many priorities lower than the
server scripting processes are created.  The first integer determines server
processes.  A second, if supplied, determines user scripts.  User scripts may
never be a higher priority that server scripts.

<CODE_EXAMPLE>
  [DclDetachProcessPriority]  1
  [DclDetachProcessPriority]  0,1
  [DclDetachProcessPriority]  1,2
<ENDCODE_EXAMPLE>

<CP> The first of these examples would set both server and user script
processes one below the server process.  The second, server scripts at the same
priority and user scripts one below.  The last, server scripts one below, and
user scripts two below.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclGatewayBG]
<EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> When enabled, non-SSL, subprocess script CGI environments have a CGI
variable WWW_GATEWAY_BG created containing the device name
(BG<EMPHASIS>(nnnn):) of the TCP/IP socket connected to the client.  This
socket may be accessed by the script for transmission of data directly to the
script bypassing the server entirely.  This is obviously much more efficient
for certain classes of script.  For purposes of accurate logging the server
does need to be informed of the quantity of data transfered using a CGI
callout.  See <QUOTE>(Scripting Environment) document.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclHardLimit] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> The maximum number of DCL/CGI script processing subprocesses that may ever
exist concurrently (works in conjunction with [DclSoftLimit].

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclScriptRunTime] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> One or more file type (extension) specification and scripting verb pairs.
See <QUOTE>(Scripting Overview, Runtime).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclSoftLimit] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

<P> 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
<QUOTE>([DclSoftLimit] = [Busy]) and <QUOTE>([DclHardLimit] = [DclSoftLimit] +
[DclSoftLimit] / 4).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclSpawnAuthPriv]
<EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> By default, when a DCL/scripting subprocess is spawned it inherits the
server's currently enabled privileges, which are <EMPHASIS>(none\BOLD), 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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DclZombieLifeTime] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))           

<P> This value represents time in minutes.  If this value is zero the use of
persistant DCL subprocesses is disabled.  If non-zero the <EMPHASIS>(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 <QUOTE>(Scripting Environment) document.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DECnetReuseLifeTime] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))              

<P> The number of minutes a DECnet scripting connection is maintained with the
network task.  Zero disables connection reuse. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DECnetConnectListMax] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))              

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirAccess] <EMPHASIS>(ENABLED<VBAR>DISABLED<VBAR>SELECTIVE\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Controls directory listings.  <EMPHASIS>(SELECTIVE\SMALLCAPS) allows access 
only to those directories containing a file 
<EMPHASIS>(.WWW_BROWSABLE\SMALLCAPS).  The WASD HTTPd directory access 
facility always ignores directories containing a file named 
<EMPHASIS>(.WWW_HIDDEN\SMALLCAPS).  Also see the [DirWildcard]
directive.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirBodyTag]  <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: <LITERAL>(<BODY>)))

<P> Specifies the HTML <LITERAL>(<BODY>) tag for directory listing pages.  This
allows some measure of site <QUOTE>(look-and-feel) in page colour, background,
etc. to be employed.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirDescriptionLines] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))              

<P> Non-Zero enables HTML file descriptions during listings.  Generating HTML
descriptions involves opening each HTML file and searching for
<LITERAL>(<TITLE>...</TITLE>) and <LITERAL>(<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).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirLayout] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: I__L__R__S__D)) 

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

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)
<LE><EMPHASIS>(C\BOLD) - creation date
<LE><EMPHASIS>(D\BOLD) - description (generally best specified last)
<LIST>(UNNUMBERED)
<LE><EMPHASIS>(D:L\BOLD) - for files, make a link out of the description text
<ENDLIST>
<LE><EMPHASIS>(I\BOLD) - icon (takes no field-width attribute)
<LIST>(UNNUMBERED)
<LE><EMPHASIS>(L\BOLD) - link (highlighted anchor using the name of the file)
<LE><EMPHASIS>(L:F\BOLD) - file-system name (for ODS-5 displays spaces, etc.) 
<LE><EMPHASIS>(L:N\BOLD) - name-only, do not display the extension
<LE><EMPHASIS>(L:U\BOLD) - force name to upper-case
<ENDLIST>
<LE><EMPHASIS>(N\BOLD) - name (no link, why bother? who knows!)
<LE><EMPHASIS>(O\BOLD) - owner (can be disabled)
<LE><EMPHASIS>(R\BOLD) - revision date
<LE><EMPHASIS>(S\BOLD) - size
<LIST>(UNNUMBERED)
<LE><EMPHASIS>(S:B\BOLD) - in bytes (comma-formatted)
<LE><EMPHASIS>(S:D\BOLD) - decimal kilos (see below)
<LE><EMPHASIS>(S:F\BOLD) - kilo and mega are displayed to one decimal place
<LE><EMPHASIS>(S:K\BOLD) - in kilo-bytes (and fractions thereof)
<LE><EMPHASIS>(S:M\BOLD) - in mega-bytes (and fractions thereof)
<ENDLIST>
<LE><EMPHASIS>(U\BOLD) - upper-case file and directory names (must be the
first character)
<ENDLIST>

<COMMENT>(HTML=<P>)

<P> The following shows some examples:

<CODE_EXAMPLE>
  [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
<ENDCODE_EXAMPLE>

<P> The size of files is displayed by default as 1024 byte kilos.  When using
the <QUOTE>(S:k), <QUOTE>(S:m) and <QUOTE>(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:

<CODE_EXAMPLE>
  [DirLayout]       I__L__R__S:d__D
<ENDCODE_EXAMPLE>

<P> If unsure of the kilo value being used check the
<QUOTE>(<LITERAL>(<META>)) information in the directory listing.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirMetaInfo] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> Includes, as <LITERAL>(<META>) information, the software ID of the server
and any relevant VMS file information.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirNoImpliedWildcard] <EMPHASIS>(ENABLED<VBAR>DISABLED \SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirNoPrivIgnore] <EMPHASIS>(ENABLED<VBAR>DISABLED \SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirOwner] <EMPHASIS>(ENABLED<VBAR>DISABLED \SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> Allows specification and display of the RMS file owner information.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirPreExpired]
<EMPHASIS>(ENABLED<VBAR>DISABLED \SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> Directory listings and trees may be <EMPHASIS>(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:

<CODE_EXAMPLE>
  /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
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirReadme] <EMPHASIS>(TOP<VBAR>BOTTOM <VBAR>
OFF\SMALLCAPS)\BOLD) <EMPHASIS>((default: DISABLED)) 

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirReadMeFile] <EMPHASIS>(file.suffix\SMALLCAPS)\BOLD)
<EMPHASIS>((no default)) 

<P> Specifies the names and order in which a directory is checked for
<EMPHASIS>(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. 

<COMMENT>(HTML=<P>)

<P> Examples: 

<CODE_EXAMPLE>
  [DirReadMeFile]
  readme.html
  readme.htm
  readme.
  readme.txt
  readme.1st
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DirWildcard] <EMPHASIS>(OFF<VBAR>ON\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED))

<P> This enables the facility to <EMPHASIS>(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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([DNSLookup] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

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

<P> This functionality significantly slows request processing.  See
<REFERENCE>(chapter_server_perf).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ErrorReportPath] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> Specifies the <EMPHASIS>(URL-format path\BOLD) to an optional, error
reporting SSI document or script. See <REFERENCE>(head_error_reporting). This
path can subsequently be remapped during request processing.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ErrorRecommend] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Provides a short message recommending action when reporting an error to a
client.  For example, if a document cannot be found it may say:

<CODE_EXAMPLE>
  <EMPHASIS>((document, or bookmark, requires revision))
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Logging] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> 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
<REFERENCE>(head_server_logical_names).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([LogExcludeHosts] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> One or more (comma-separated if on the same line) internet host/domain
names, with <QUOTE>(*) 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.

<P> Example: 

<CODE_EXAMPLE>
  [LogExcludeHosts]
  *.wasd.dsto.defence.gov.au
  131.185.250.*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([LogFormat] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: COMMON)) 

<P> Specifies one of three pre-defined formats, or a user-definable format.
See <REFERENCE>(head_log_format).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([LogNaming] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> 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 <REFERENCE>(head_log_naming).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([LogPeriod] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> Specifies a period at which the log file is changed.
See <REFERENCE>(head_log_period).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([LogPerService] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> When multiple services are specified (see <REFERENCE>(head_virtual_services)) 
a separate log file will be created for each if this is enabled. See
<REFERENCE>(head_log_per_service).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([LogPerServiceHostOnly] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> When generating a log name do not make the port number part of it.  This
effectively provides a single log file for all ports provided against a host
name (e.g. a standard HTTP service on port 80 and an SSL service on port 443
would have entries in the  one file). See <REFERENCE>(head_log_per_service).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Monitor] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Allows monitoring via the HTTPDMON utility (see <REFERENCE>(head_httpdmon). 
Adds slight request processing overhead.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([OpcomAdmin] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Report to operator log and any enabled operator console (see [OpcomTarget])
server administartion directives originating from the Server Administration
Menu, for example path map reload, server restart, etc.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([OpcomAuthorization] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Report events related to authentication/authorization.  For example
username-password validation failures.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([OpcomControl] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Report HTTPD/DO=<EMPHASIS>(directive) control events, both the command-line
directive and the server's response.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([OpcomHTTPd] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Report events concerning the server itself.  For example, server startup
and exit (either normally or with error status).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([OpcomProxyMaint] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Report events related to proxy server cache maintenance.  For example, the
commencement of file cache reactive and proactive purging, the conclusion of
this purge, both with cache device statistics.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([OpcomTarget] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> This enables OPCOM messaging and specifies the target for the OPCOM
reports.  This must be set to a target to enable OPCOM messages, irrespective
of the setting of any of the other [Opcom...] directives.  These messages are
added to SYS$MANAGER:OPERATOR.LOG and displayed at the specified operator's 
console if enabled (using REPLY/ENABLE=target).  The operator log provides a
<QUOTE>(permanent) record of server events.  Possible settings include
CENTRAL, NETWORK, SECURITY, OPER1 <HELLIPSIS> OPER12, etc.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Port] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 80)) 

<P> IP port number for server to bind to.  For anything other than a
command-line server control (see <REFERENCE>(head_httpd_control)) this
parameter is overridden by anything supplied via the [Service] directive.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyForwardedBy] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables and disables the addition of a proxy request header line providing
information that the request has been forwarded by another agent.  The added
header line would look like <QUOTE>(Forwarded: by http://host.name.domain
(HTTPd-WASD/n.n.n OpenVMS/AXP Digital-TCPIP SSL)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyHostLookupRetryCount] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0)) 

<P> When the server is resolving the name of a remote host the request may
timeout due to up-stream DNS server latencies.  This parameter allows a number
of retries, at five second intervals, to be enabled.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyReportLog] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables the server process log reporting siginificant proxy
processing events, such as cache maintenance activity.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyReportCacheLog] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables the server process log reporting of proxy caching
activity.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyServing] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables proxy serving on a whole-of-server basis, irrespective
of any proxy services that might be configured.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCache] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables proxy caching on a whole-of-server basis, irrespective
of any proxy services that might be configured for caching.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCacheFileKBytesMax] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 256)) 

<P> Maximum size of a cache file in kilobytes before it will not be cached.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCacheRoutineHourOfDay] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0)) 

<P> Hour of day for <EMPHASIS>(routine) cache purge (00-23).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCacheDeviceCheckMinutes] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 15)) 

<P> Interval in minutes between checking space availablility on cache device. 
If space is not available a <EMPHASIS>(reactive) purge is initiated.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCacheDeviceDirOrg] <EMPHASIS>(FLAT256<VBAR>64X64\SMALLCAPS)\BOLD)
<EMPHASIS>((default: FLAT256)) 

<P> Organization of directories on the proxy cache device.  The first provides
a single level structure with a possible 256 directories at the top level and
files organized immediately below these. For versions of VMS prior to V7.2
exceeding 256 files per directory, or a total of approximately 65,000 files,
incurs a significant performance penalty for some directory operations.  The
second organization involves two levels of directory, each with a maximum of
64 directories.  This allows for approximately 1,000,000 files before
encountering the 256 file per directory issue.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCacheDeviceMaxPercent] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 85)) 

<P> The maximum percentage in use on the cache device before a
<EMPHASIS>(reactive) purge is scheduled.  If device usage exceeds this limit no
more cache files are created.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCacheDevicePurgePercent] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 1)) 

<P> The percentage by which the cache device usage is attempted to be reduced
when a <EMPHASIS>(reactive) purge is initiated.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCachePurgeList] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: 168,48,24,8,0)) 

<P> A list of comma-separated integers representing the sequence of last
accessed period in hours used during a progressive <EMPHASIS>(reactive) purge.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyCacheReloadList] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: 1,2,4,8,12,24,48,96,168)) 

<P> A list of comma-separated integers representing the sequence of age in
hours used when determining whether a cache file's contents should be reloaded.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ProxyHostCachePurgeHours] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 24)) 

<P> The period at which the cache of host names to IP addresses is purged.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([PutMaxKBytes] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 250)) 

<P> Maximum size of an HTTP POST or PUT method request in Kilobytes.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([PutVersionLimit] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 3)) 

<P> File created using the POST or PUT methods have the specified version limit
applied.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Reject] <EMPHASIS>(host/domain name)\BOLD)
<EMPHASIS>((default: none))

<P> One or more (comma-separated if on the same line) internet host/domain
names, with <QUOTE>(*) 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.

<P> Example: 

<CODE_EXAMPLE>
  [Reject]
  *.wasd.dsto.defence.gov.au
  131.185.250.*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ReportBasicOnly] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> Only ever supply basic information in a report (see
<REFERENCE>(head_error_reporting)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ReportMetaInfo] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD) 
<EMPHASIS>((default: DISABLED)) 

<P> Includes in detailed reports, as <LITERAL>(<META>) information, the
software ID of the server and any relevant VMS file information.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([RequestHistory] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0))

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Scripting] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: ENABLED)) 

<P> Enables and disables <EMPHASIS>(all\BOLD) scripting mechanisms.  This
includes subprocess CGI and CGIplus, DECnet-based OSU and CGI, and SSI
directives that DCL subprocesses to provide <LITERAL>(<--#dcl -->),
<LITERAL>(<--#exec -->), etc. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([SearchScript] <EMPHASIS>(path)\BOLD)
<EMPHASIS>((no default)) 

<P> Specifies the <EMPHASIS>(URL-format path\BOLD) to the default query-string 
keyword search script.  This path can subsequently be remapped during request
processing.

<P> Example: 

<CODE_EXAMPLE>
  [SearchScript] /ht_root/script/query
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([SearchScriptExclude] <EMPHASIS>(list)\BOLD)
<EMPHASIS>((no default)) 

<P> Provides a list of file types that are excluded from an implied keyword
search. This is useful for client-side (browser-side) active processing that
may require a query string to pass information.  This query string would
normally be detected by the server and if not in a format to be meaningful to
itself is then considered as an implied (<LITERAL>(HTML <ISINDEX>)) keyword
search, with the approriate script being activiated.

<P> Example: 

<CODE_EXAMPLE>
  [SearchScriptExclude] .HTA,.HTL
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServerAdmin] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((no default)) 

<P> Specifies the contact email address for server administration issues. 
Included as a <QUOTE>(mailto:) link in the server signature if
[ServerSignature] is set to <EMPHASIS>(email).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServerAdminBodyTag]  <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: <LITERAL>(<BODY>)))

<P> Specifies the HTML <LITERAL>(<BODY>) tag for server administration and
administration report pages.  This allows some measure of control over the
<QUOTE>(look-and-feel) of page and link colour, etc.. for the administrator.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServerReportBodyTag]  <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: <LITERAL>(<BODY>)))

<P> Specifies the HTML <LITERAL>(<BODY>) tag for server error and other report
pages.  This allows some measure of site <QUOTE>(look-and-feel) in page colour,
background, etc. to be maintained.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServerSignature]
<EMPHASIS>(ENABLED<VBAR>EMAIL<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> The server signature is a short identifying string added to server
generated error and other report pages.  It includes the server software name
and version, along with the host name and port of the service.  Setting this to
<EMPHASIS>(email) makes the host name a <EMPHASIS>(mailto:) link containing the
address specified by the [ServerAdmin] directive.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Service] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((no default)) 

<P> This parameter allows SSL, multi-homed hosts and multiple port serving to
be specified, see <REFERENCE>(head_ssl_config) and
<REFERENCE>(head_virtual_services).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceNotFoundURL] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((no default)) 

<P> Provides a default path for reporting a virtual host does not exist, see
<REFERENCE>(head_virtual_unknown).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([SSI] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables Server Side Includes (HTML pre-processing).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([SSIaccesses] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables Server Side Includes (HTML pre-processing) file access
counter.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([SSIexec] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables or disables Server Side Includes (HTML pre-processing) DCL
execution functionality.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([StreamLF] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0 (disabled))) 

<P> 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 any conversions.  See
<REFERENCE>(head_perf_record_format).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([StreamLFpaths] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((no default)) 

<P> <EMPHASIS>((Retired in v5.3, mapping SET rule provides this now, see
<REFERENCE>(head_set_rules))).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([TimeoutInput] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 1)) 

<P> Number of minutes to allow a connection request to be in progress without 
submitting a complete request header before terminating it. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([TimeoutKeepAlive] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 5)) 

<P> Number of seconds a <QUOTE>(Keep-Alive:) request connection is maintained
after the conclusion of a request.  <EMPHASIS>(Keep-Alive) improves the overall
performance of the server by reducing the number of discrete TCP/IP connections
that need to be establiched.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([TimeoutNoProgress] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 2)) 

<P> Number of minutes to allow request output to continue without any increase
in the number of bytes transfered.  This directive is targeted at identifying
and eliminating requests that have stalled.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([TimeoutOutput] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 10)) 

<P> Number of minutes to allow a request to be output before terminating it. 
This directive sets an absolute maximum time a request can continue to receive
output.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Track]  <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables session (user) tracking.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([TrackMultiSession]  <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> By default the tracking cookie is discarded by the browser when it is
closed.  This setting directs the browser to keep it between sessions.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([TrackDomain] <EMPHASIS>(file.suffix)\BOLD)
<EMPHASIS>((no default)) 

<P> User tracking applies only to the originating (virtual) server by default. 
This directive allows it to applied to all a particular domain's sites. 
Top-level sites (e.g. those in <QUOTE>(.com), <QUOTE>(.edu) etc.) would specify
this as something like <EMPHASIS>(organization.domain) (i.e. two dots), while
other would use <EMPHASIS>(organization.group.domain) (i.e. three dots).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([Welcome] <EMPHASIS>(file.suffix)\BOLD)
<EMPHASIS>((no default)) 

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

<COMMENT>(HTML=<P>)

<P> Examples: 

<CODE_EXAMPLE>
  [Welcome]
  home.html
  home.htm
  home.menu
  home.mnu
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Service Configuration\chapter_service_directives)

<NOTE>
The service configuration file is optional.  If the HTTPD$SERVICE logical is
not defined or the file does not exist service configuration is made using the
HTTPD$CONFIG [Service] directives.  For simple sites, those containing one or
two services, the use of a separate service configuration file is probably not
warranted.  Once the number begins to grow this file offers a specific
management interface for those services.
<ENDNOTE>

<P> Precedence of service specifications:

<LIST>(NUMBERED)
<LE> /SERVICE= command line qualifier
<LE> HTTPD$SERVICE configuration file (if logical defined and file exists)
<LE> HTTPD$CONFIG [Service] directive
<ENDLIST>

<P> In common with other configuration files, directives associated with a
specific virtual services are introduced using a double-bracket delimited host
specification (see <REFERENCE>(head_virtual_services)).  When configuring a
service the following three components specify its essential characteristics.

<LIST>(NUMBERED)

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(scheme - \BOLD) HTTP scheme (sometimes refered to as
<EMPHASIS>(protocol)).  If <EMPHASIS>(http:) (or omitted) it is a standard HTTP
service.  If <EMPHASIS>(https:) an SSL service is configured.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(host - \BOLD) Host name or dotted-decimal address.  If omitted,
or specified as an asterisk (<QUOTE>(*)), defaults to the system's IP host name.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(port - \BOLD) IP port the service is offered on.  If omitted the
it defaults to 80 for an <EMPHASIS>(http:) service, and to 443 for an
<EMPHASIS>(https:) (SSL) service.

<ENDLIST>

<HEAD>(Generic Services\head_service_generic)

<P> A <EMPHASIS>(generic) service is one that specifies a scheme and/or port
but no specific host name.  This is useful in a cluster where multiple systems
all provide a basic service (e.g. a port 80 service).  If the host name is
omitted or specified as an asterisk the service substitutes the system's IP
host name.  See <REFERENCE>(head_service_directives_example).

<HEAD>(SSL Services\head_service_ssl)

<P> Multiple virtual SSL services (https:) sharing the same certificate can
essentially be configured against any host name (unique IP address or alias)
and/or port in the same way as standard services (http:).  Services requiring
unique certificates can only be configured for the same port number against
individual and unique IP addresses (i.e. not against aliases).  This is not a
WASD restriction, it applies to all servers for significant SSL technical
reasons (see <REFERENCE>(chapter_ssl)).

<P> For example, unique certificates for https://www.company1.com:443/ and
https://www.company2.com:443/ can be configured only if COMPANY1 and COMPANY2
have unique IP addresses.  If COMPANY2 is an alias for COMPANY1 they must share
the same certificate.  During startup service configuration the server checks
for such conditions and issues a warning about <QUOTE>(sharing) the service
with the first configured.

<HEAD1>(Service Directives\head_service_directives)

<P> Where a service directive has an equivalent configuration directive (e.g.
error report path) the service directive takes precedence.  This allows
specific virtual services to selectively override the generic configuration.

<P>
<CENTER_LINE>(<EMPHASIS>(Service Directives\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_ROW>(<EMPHASIS>([[virtual-service]]\BOLD)\scheme://host:port)
<TABLE_ROW>(<EMPHASIS>(ServiceBodyTag\BOLD)\<LITERAL>(<BODY>) tag for server
reports., etc)
<TABLE_ROW>(<EMPHASIS>(ServiceErrorReportPath\BOLD)\path to script, SSI or
<QUOTE>(flat) error document)
<TABLE_ROW>(<EMPHASIS>(ServiceIpaddress\BOLD)\if different to host's)
<TABLE_ROW>(<EMPHASIS>(ServiceNoLog\BOLD)\suppress logging)
<TABLE_ROW>(<EMPHASIS>(ServiceNoTrack\BOLD)\suppress user tracking)
<TABLE_ROW>(<EMPHASIS>(ServiceProxy\BOLD)\proxy service)
<TABLE_ROW>(<EMPHASIS>(ServiceProxyAuth\BOLD)\require proxy authorization)
<TABLE_ROW>(<EMPHASIS>(ServiceProxyCache\BOLD)\proxy caching)
<TABLE_ROW>(<EMPHASIS>(ServiceProxyChain\BOLD)\chained proxy service host)
<TABLE_ROW>(<EMPHASIS>(ServiceProxyTrack\BOLD)\user track proxy access)
<TABLE_ROW>(<EMPHASIS>(ServiceProxySSL\BOLD)\provide proxy of SSL (connect:))
<TABLE_ROW>(<EMPHASIS>(ServiceSSLcert\BOLD)\SSL service certificate)
<TABLE_ROW>(<EMPHASIS>(ServiceSSLkey\BOLD)\SSL service private key)
<ENDTABLE>

<HEAD1>(Directive Detail\head_service_directives_detail)

<COMMENT>(HTML=<BR>)

<LIST>(NUMBERED)

<LE> <EMPHASIS>([[virtual-service]]\BOLD)
<EMPHASIS>((default: <EMPHASIS>(none)))

<P> Specifies the scheme, host name (or asterisk) and port of a service.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceBodyTag]  <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: <LITERAL>(<BODY>)))

<P> Specifies the HTML <LITERAL>(<BODY>) tag for server error and other report
pages.  This allows some measure of site <QUOTE>(look-and-feel) in page colour,
background, etc. to be maintained.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceErrorReportPath] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> Specifies the <EMPHASIS>(URL-format path\BOLD) to an optional, error
reporting SSI document or script. See <REFERENCE>(head_error_reporting). This
path can subsequently be remapped during request processing.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceIpAddress] <EMPHASIS>(dotted-decimal address)\BOLD)
<EMPHASIS>((default: <EMPHASIS>(none))) 

<P> If the system has a multi-homed network interface this binds the service to
the specific IP address and not to INADDR_ANY.  Generally this will not be
necessary.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceNoLog] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> When request logging is enabled then by default all services are logged.
This directive allows logging to be suppressed for this service. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceNoTrack] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> When use tracking is enabled then by default all requests on non-proxy
services are tracked. This directive allows tracking to be suppressed for this
service. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceProxy] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables and disables proxy request processing for this service. For proxy
serving detail see <REFERENCE>(chapter_proxy_serving).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceProxyAuth] <EMPHASIS>(<EMPHASIS>(none)<VBAR>AUTH<VBAR>LOCAL\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Makes a proxy service require authorization before a client is allowed
access via it. <EMPHASIS>(none\SMALLCAPS) disables authorization.
<EMPHASIS>(PROXY\SMALLCAPS) enables HTTP proxy authorization.
<EMPHASIS>(LOCAL\SMALLCAPS) enables standard server authorization.
See <REFERENCE>(head_proxy_control).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceProxyCache] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Enables and disables proxy caching for a proxy service.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceProxyChain] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> Specifies the next proxy host if chained.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceProxyTrack] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> When user tracking is enabled only non-proxy services have it applied by
default.  This directive allows proxy service usage tracking to be enabled.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceProxySSL] <EMPHASIS>(ENABLED<VBAR>DISABLED\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> Specifies the service as providing proxying of SSL requests.  This is
sometimes refered as a <QUOTE>(connect) service.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceSSLcert] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> Specifies the location of the SSL certificates (VMS file specification).
See <REFERENCE>(head_ssl_config).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([ServiceSSLkey] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: none)) 

<P> Specifies the location of the SSL private key (VMS file specification).

<ENDLIST>

<HEAD1>(Administration\head_service_directives_admin)

<P> A service configuration file can be maintained using a simple text editor
and HTTPD$SERVICE.

<P> Alternatively the server administration menu may be used. See
<REFERENCE>(chapter_server_admin).  When using this interface for the first
time ensure the HTTPD$SERVICE logical is correctly defined.  If the file did
not exist at server startup any services will have been created from the
HTTPD$CONFIG [Service] directive.  These will be displayed as the existing
services and will be saved to the configuration file the first time it is
saved.

<P> Not all configuration directives may be shown depending on the type of
service.  For instance, unless a service is configured to provide proxy, only
the [ServiceProxy] directive is displayed.  To fully configure such a service
enable it as proxy, save the file, then reload it.  The additional directives
will now be available.

<P> There is always one empty service displayed each time the configuration
menu is generated.  This information may be changed appropriately and then
saved to add new services to the configuration (of course, these will not be
available until the server is restarted).  To configure multiple new services
add one at a time, saving each and reloading the file to provide a new blank
service.

<HEAD1>(Examples\head_service_directives_example)

<LIST>(NUMBERED)

<LE> The following example shows three services being configured.  The first is 
standard HTTP on the default (and well-known) port 80.  The second is a proxy
service on port 8080.  This service provides both standard HTTP (with response
caching enabled), SSL (connect:) access and proxy authorization required.  The
third service is SSL, with a host-specific certificate and key.

<CODE_EXAMPLE>
  [[http://alpha.wasd.dsto.defence.gov.au:80]]

  [[http://alpha.wasd.dsto.defence.gov.au:8080]]
  [ServiceProxy]  enabled
  [ServiceProxyAuth]  PROXY
  [ServiceProxyCache]  enabled
  [ServiceProxySSL]  enabled

  [[https://alpha.wasd.dsto.defence.gov.au:443]]
  [ServiceSSLcert] ht_root:[local]alpha.pem
<ENDCODE_EXAMPLE>

<LE> This example shows a generic service service being configured on the
well-known port 80.

<CODE_EXAMPLE>
  [[http://*:80]]
<ENDCODE_EXAMPLE>

<CP> If a cluster of four systems, ALPHA, BETA, GAMMA and DELTA
all use this configuration each will have a service accessable via the
following four URLs.

<CODE_EXAMPLE>
  http://alpha.domain.name/
  http://beta.domain.name/
  http://gamma.domain.name/
  http://delta.domain.name/
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Message Configuration\chapter_msg_config)

<P> Message configuration is provided for two purposes.

<LIST>(NUMBERED)

<COMMENT>(HTML=<P>)

<LE> Some sites would prefer to customize or extend the basic information
provided to clients when an error or other event occurs.

<COMMENT>(HTML=<P>)

<LE> Sites that do not use English as a first language may wish to provide
some or all of the defined messages using a prefered language.

<ENDLIST>

<P> Not all messages provided by the WASD server are customizable, only those
generated for non-administrative content. As the WASD server can also report
using information derived from the standard VMS message service (via
<EMPHASIS>(sys$getmsg())) it is assumed a language-local implementation of
this is in use as well. Unfortunately for the non-first-language-English Web
and system administrators, the menus and messages used for administration
purposes, etc., are still only in English. The intent of this facility is to
provide non-administration clients only with a more familiar language
environment.

<P> Also note that the message database only applies to messages generated by
the server, not to any generated by scripts, etc.

<HEAD1>(Behaviour\head_msg_behaviour)

<P> When an error, or other message or string, needs to be provided for the
client the message database is accesssed using the following algorithm.

<LIST>(NUMBERED)

<LE> If the client request has specified a list of prefered languages using
the <QUOTE>(Accept-Language:) HTTP header field the message database is
checked for support of that/those languages. If one is found then that
language is used to access the message.

<COMMENT>(HTML=<P>)

<LE> If none is found, or the client has not specified a prefered language,
the client host address is checked against any list of hosts/domains provided
against the language (see below). If a match occurs the specified language is
used.

<COMMENT>(HTML=<P>)

<LE> If neither of the above results in a message language the base language
is used (the highest numbered language). This <EMPHASIS>(must\BOLD) have a
complete set of messages or the server will not start!

<ENDLIST>

<HEAD1>(Message File Format\head_msg_format)

<P> By default, the system-table logical name HTTPD$MSG locates a common
message file, unless an individual message file is specified using a job-table
logical name. Simple editing of the message file changes the messages (after a
server restart, of course). Comment lines may be included by prefixing them
with the hash character (<QUOTE>(#)), and lines continued by ensuring the last
character is a backslash (<QUOTE>(<BACKSLASH>)). The server will concurrently
support an additional 3 languages to the base English (although this can be
increased by recompilation :^)

<NOTE>
Care must be taken with the message file or the server may refuse to start!
<ENDNOTE>

<COMMENT>(HTML/OFF)
<P><EMPHASIS>(Care must be taken with the message file or the server may
refuse to start\BOLD)
<COMMENT>(HTML/ON) 

<P> As illustrated below the message file comprises a series of sections.
Directives enclosed by square-brackets provide information to the message
loader.

<CODE_EXAMPLE>
  # this is a comment

  [version] 4.4
  [language] 1 se *.se
  [language] 2 de *.de,*.su
  [language] 3 en

  [general]

  en 01 Sanity check failure.
  de 01 (the same message but in German, which I cannot speak :^)
  se 01 (the same message but in Swedish, which I also cannot speak :^)
  en 02 String overflow.
  de 02 (the same message but in German, which I cannot speak :^)
  se 01 (the same message but in Swedish, \
  which I still cannot speak :^) \
  this has also been continued over two additional lines!
  en 03 Heap allocation failed.
  en 04 calloc() failed
  en 05 Request calloc() failed.
  en 06 Server too busy.
  en 07 Server access denied.
  en 08 Facility is disabled.
  en 09 Wildcard not permitted.
  en 10 Directory layout problem.

  [next-section, etc.]
<ENDCODE_EXAMPLE>

<CP> The square-bracketed section headings have the following functions.

<LIST>(NUMBERED)

<LE> <EMPHASIS>([version] - \BOLD) Ensures the correct database version is
available for the server version attempting to use it. The message file always
needs checking for this version number being changed at server updates,
although the version may remain fixed at a previous server version number if
there have been no changes to the message database during subsequent server
versions. This must be the first directive in the file.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([language] - \BOLD) Creates space for assigning the new
language's messages.

The number specifies an order within the languages, each must be different,
but only the lowest and highest (prefered and base respectively) have
operational significance. The highest number should always be English to
provide a fall-back message. A short string provides an identifier for the
language. This identifier should be the same as the identifying string in the
browser request <QUOTE>(Accept-Language:) header field (e.g. <QUOTE>(en),
<QUOTE>(se), <QUOTE>(de), <QUOTE>(fr), etc.) Following the language identifier
is an optional host/domain list. Multiple hosts/domains may be specified by
separating each with a comma. The specifications may contain wildcards. All
the [language] directives should be grouped at the start of the file
immediately following the [version] directive. Setting the language's ordering
number to zero disables the language completely. All messages associated with
it will then be ignored.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([group-name] - \BOLD) The messages are divided into
groupings to make them easier to manage.  Each group begins with the group
name directive.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(en 01 message - \BOLD) Each message in a group is assigned
using using this format.  The string identifying the language, then the
message number (the leading zero just improves the format, strictly it is not
required), then the actual message itself.  The message can be of arbitrary
length.  Long messages may be continued on following lines using the
<QUOTE>(<BACKSLASH>) continuation character.

<ENDLIST>

<P> The base language (the highest numbered, which should always be English)
must have precisely the right number of messages required by the server, too
few or too many and the server will not start! <EMPHASIS>(Additional languages
do not have to reassign every message!\BOLD) The base language will supply any
not assigned. A message number of zero is disabled and completely ignored.

<P> If messages contain HTML tags that markup must not interfere with the
general HTML page it is used within.

<P> Some messages are a composite of multiple strings each of which is used on
a different part of the one page (e.g. for the [upd] edit-page).  Each of the
strings is delimited by the vertical bar <QUOTE>(<LITERAL>(|)).  Care must be
taken when customizing these strings that the overall number stays the same and
that the length of each does not become excessive.  Although it will not
disrupt the server it may significantly disrupt the page layout.

<P> All message numbers must be included.  To provide an empty string for any
one message (not recommended) provide the line with nothing following the
message number.

<HEAD1>(Supplied Message Files\head_msg_supplied)

<P> Any non-English message files that are provided to the author will be
included for general use (please take the time to support this endeavour) in
the

<COMMENT>(HTML=
<A HREF="/ht_root/example/httpd$msg*.conf">HT_ROOT:[EXAMPLE]</A> directory.
)

<COMMENT>(HTML/OFF)
HT_ROOT:[EXAMPLE] directory.
<P><BOX>(online hypertext link)
<COMMENT>(HTML/ON)

<P> Note that message files can become out-of-date as server versions change,
requiring modifications to the message database.  Check the version information
and/or comments at the top of candidate message files, however even slightly
dated files may serve as a good starting point for a locale-specific message
base.

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Mapping Rules\chapter_mapping_rule)

<P> Mapping rules are used in five primary ways.

<LIST>(NUMBERED)

<LE> To map a request <EMPHASIS>(path) onto the VMS file system.

<COMMENT>(HTML=<P>)

<LE> To process a request path according to specified criteria resulting in an
effective path that is different to that supplied with the request.

<COMMENT>(HTML=<P>)

<LE> To identify requests requiring script activation and to parse the script
from the path portion of that request.  The path portion is then independently
re-mapped.

<COMMENT>(HTML=<P>)

<LE> To conditionally map to different end-results based on one or more
criteria of the request.

<COMMENT>(HTML=<P>)

<LE> To provide differing virtual sites depending on the actual service
accessed by the client.

<ENDLIST>

<P> Mapping is basically for server-internal purposes only. The only time the
path information of the request itself is modified is when a script component
is removed. At all other times the path information remains unchanged.  Path
authorization is always applied to the path supplied with the request.

<P> By default, the system-table logical name HTTPD$MAP locates a common
mapping rule file, unless an individual rule file is specified using a job-
table logical name. Simple editing of the mapping file changes the rules.
Comment lines may be included by prefixing them with the hash <QUOTE>(#)
character. Although, there is no fixed limit on the number of rules there are
the processing implications of scanning a large, linear database. 

<P> Rules are given a basic consistency check when loaded (i.e. server
startup, map reload, etc.) If there is an obvious problem (unknown rule,
missing component, etc., path not absolute) a warning message is generated and
the rule is not loaded into the database. This will not cause the server
startup to fail. These warning messages may be found in the server process
log. 

<P> <EMPHASIS>(The server administration facility allows realm and arbitrary
paths to be checked against the rule database in real-time using the WATCH
facility.\BOLD) See <REFERENCE>(chapter_watch). In this way the rule database
may be checked against test or even live requests.

<P> Any changes to the mapping file may be (re)loaded into the running HTTPd 
server using the following command on the server system: 

<CODE_EXAMPLE>
  $ HTTPD /DO=MAP
<ENDCODE_EXAMPLE>

<P> Also see <REFERENCE>(chapter_config) for daemon configuration. 

<HEAD>(Server Mapping Rules\head_current_server_mapping)

<P> A server's currently loaded mapping rules may be interrogated.  See
<REFERENCE>(chapter_server_admin) for further information.

<HEAD>(Mapping Overhead\head_mapping_overhead)

<P> Naturally, each rule that needs to be processed adds a little to consumed
CPU, introduces some latency, and ultimately reduces throughput.  The
test-bench has shown this to be acceptably small compared to the overall costs
of responding to a request.  Using the ApacheBench tool on a DEC 3000 Model 300
running OpenVMS V7.2-1 with a simple access to /ht_root/exercise/0k.html showed
approximately 60 requests/second throughput using the following mapping file.

<CODE_EXAMPLE>
  pass /ht_root/exercise/* 
<ENDCODE_EXAMPLE>

<P> After adding various quantities of the same intervening rule

<CODE_EXAMPLE>
  pass /ht_root/example/* 
  pass /ht_root/example/* 
    .
    .
    .
  pass /ht_root/example/* 
  pass /ht_root/exercise/* 
<ENDCODE_EXAMPLE>

<CP> the following results were derived.

<P>
<CENTER_LINE>(<EMPHASIS>(Mapping Overhead\BOLD))
<TABLE>
<TABLE_SETUP>(3\20\20)
<TABLE_HEADS>(Intervening Rules\Requests/S\Throughput)
<TABLE_ROW>(0\60\benchmark)
<TABLE_ROW>(100\57\-5%)
<TABLE_ROW>(200\54\-10%)
<TABLE_ROW>(500\48\-20%)
<ENDTABLE>

<P> Although this is a fairly contrived set-up and actual real-world rule-sets
are more complex than this, even one hundred rules is a <UNDERLINE>(very) large
set, and it does indicate that for all intents and purposes mapping rules can
be used to achieve desired objectives without undue concern about impact on
server throughput.

<HEAD1>(VMS File System Specifications\head_mapping_vms)

<P> The VMS file system in mapping rules is always assumed to begin with a
device or concealed device logical. Specifying a Master File Directory (MFD)
component, the [000000] is completely optional, although always implied. The
mapping functions will always insert one if required for correct file system
syntax. That is, if the VMS file system mapping of a path results in a file in
a top-level directory an MFD is inserted if not explicitly present in the
mapping.  For example, both of the following paths

<CODE_EXAMPLE>
  /dka100/example.txt
  /dka100/000000/example.txt
<ENDCODE_EXAMPLE>

<CP> would result in a mapping to

<CODE_EXAMPLE>
  DKA100:[000000]EXAMPLE.TXT
<ENDCODE_EXAMPLE>

<CP> The MFD is completely optional when both specifying paths in mapping
rules and when supplying paths in a request.  Similarly, when supplying a path
that includes directory components, as in

<CODE_EXAMPLE>
  /dka100/dir1/dir2/example.txt
  /dka100/000000/dir1/dir2/example.txt
<ENDCODE_EXAMPLE>

<CP> both mapping to

<CODE_EXAMPLE>
  DKA100:[DIR1.DIR2]EXAMPLE.TXT
<ENDCODE_EXAMPLE>

<NOTE>(Implication)
When using logical names in file system mappings they must be able to be used
as concealed devices and cannot be logical equivalents of directory
specifications.
<ENDNOTE>

<P> Concealed device logicals are created using the following syntax:

<CODE_EXAMPLE>
  $ DEFINE LOGICAL_NAME device:[dir1.dir2.]
  $ DEFINE LOGICAL_NAME /TRANSLATION=CONCEALED physical_device:[dir1.dir2.]
<ENDCODE_EXAMPLE>

<P> For ODS-2 volumes (see <REFERENCE>(head_mapping_extended) immediately
below), when during rule mapping of a path to a VMS file specification an
RMS-invalid character (e.g. <QUOTE>(+)) or syntax (e.g. multiple periods) is
encountered a dollar symbol is substituted in an attempt to make it acceptable. 
This functionality is often useful for document collections imported to the
local web originating from, for instance, a Unix site that utilizes non-RMS
file system syntax.  The default substitution character may be changed on a
per-path basis using the SET rule, <REFERENCE>(head_set_rules).

<HEAD1>(Extended File Specifications (ODS-5)\head_mapping_extended)

<P> OpenVMS Alpha V7.2 introduced a new on-disk file system structure, ODS-5. 
This brings to VMS in general, and WASD and other Web servers in particular, a
number of issues regarding the handling of characters previously not
encountered during (ODS-2) file system activities.  It is necessary to
distinguish paths to ODS-5, extended specification volumes from the default
ODS-2 ones.  See <REFERENCE>(head_set_rules).

<HEAD2>(Characters In Request Paths\head_mapping_extended_paths)

<P> There is a standard for characters used in HTTP requests paths and query
strings (URLs).  This includes conventions for the handling of reserved
characters, for example <QUOTE>(?), <QUOTE>(+), <QUOTE>(&), <QUOTE>(=)
that have specific meanings in a request,  characters that are completely
forbidden, for example white-space, control characters (0x00 to 0x1f), and
others that have usages by convention, for example the <QUOTE>(~), commonly
used to indicate a username mapping.  The request can otherwise contain these
characters provided they are URL-encoded (i.e. a percentage symbol followed by
two hexadecimal digits representing the hexadecimal-encoded character value).

<P> There is also an RMS standard for handling characters in extended file
specifications, some of which are forbidden in the ODS-2 file naming
conventions, and others which have a reserved meaning to either the command-line
interpreter (e.g. the space) or the file system structure (e.g. the <QUOTE>(:),
<QUOTE>([), <QUOTE>(]) and <QUOTE>(.)).  Generally the allowed but reserved
characters can be used in ODS-5 file names if escaped using the <QUOTE>(^)
character.  For example, the ODS-2 file name <QUOTE>(THIS_AND_THAT.TXT) could
be named <QUOTE>(This^_^&^_That.txt) on an ODS-5 volume.  More complex rules
control the use of character combinations with significance to RMS, for
instance multiple periods.  The following file name is allowed on an ODS-5
volume, <QUOTE>(A-GNU-zipped-TAR-archive^.tar.gz), where the non-significant
period has been escaped making it acceptable to RMS.

<P> The WASD server will accept request paths for file specifications in both
formats, URL-encoded and RMS-escaped.  Of course characters absolutely
forbidden in request paths must still be URL-encoded, the most obvious example
is the space.  RMS will accept the file name <QUOTE>(This^ and^ that.txt) (i.e.
containing escaped spaces) but the request path would need to be specified as
<QUOTE>(This%20and%20that.txt), or possibly <QUOTE>(This^%20and^%20that.txt)
although the RMS escape character is basically redundant.

<P> Unlike for ODS-2 volumes, ODS-5 volumes do not have <QUOTE>(invalid)
characters, so no processing is performed to ensure RMS compliance.

<HEAD2>(Characters In Server-Generated Paths\head_mapping_generated_paths)

<P> When the server generates a path to be returned to the browser, either in a
viewable page such as a directory listing or error message, or as a part of the 
HTTP transaction such as a redirection, the path will contain the URL-encoded
equivalent of the <EMPHASIS>(canonical form) of an extended file specification
escaped character.  For example, the file name <QUOTE>(This^_and^_that.txt)
will be represented by <QUOTE>(This%20and%20that.txt).

<P> When presenting a file name in a viewable page the general rule is to also
provide this URL-equivalent of the unescaped file name, with a small number of
exceptions.  The first is a directory listing where VMS format has been
requested by including a version component in the request file specification. 
The second is in similar fashion, but with the <EMPHASIS>(tree) facility,
displaying a directory tree.  The third is in the navigation page of the
<EMPHASIS>(UPDate) menu.  In all of the instances the canonical form of the
extended file specification is presented (although any actual reference to the
file is URL-encoded as described above). 

<HEAD1>(Rules\head_rules)

<P> There are seven mapping rules.

<LIST>(UNNUMBERED)

<LE> Rules that map paths to the file system, and to other paths:
<LIST>(UNNUMBERED)
<LE> MAP
<LE> PASS
<LE> FAIL
<LE> REDIRECT
<LE> USER
<ENDLIST>

<LE> Rules that provide access to scripting:
<LIST>(UNNUMBERED)
<LE> EXEC
<LE> SCRIPT
<LE> UXEC
<ENDLIST>

<LE> A rule that sets characteristics against particular paths:
<LIST>(UNNUMBERED)
<LE> SET
<ENDLIST>

<ENDLIST>

<HEAD2>(MAP, PASS, FAIL Rules\head_map_rules)

<LIST>(NUMBERED)

<LE> <EMPHASIS>(map <EMPHASIS>(template result)\BOLD)

<P> If the URL path matches the template, substitute the <EMPHASIS>(result) 
string for the path and use that for further rule processing.  Both template
and result paths must be absolute (i.e. begin with <QUOTE>(/)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(pass <EMPHASIS>(template)\BOLD) 
<LINE> <EMPHASIS>(pass <EMPHASIS>(template result)\BOLD) 
<LINE> <EMPHASIS>(pass <EMPHASIS>(template <QUOTE>(999 message text))\BOLD) 

<P> If the URL path matches the template, substitute the result if present (if 
not just use the original URL path), processing no further rules. 

<P> The <EMPHASIS>(result) should be a either a physical VMS file system
specification in URL format or an <EMPHASIS>(HTTP status-code message) (see
below). If there is a direct correspondance between the <EMPHASIS>(template)
and <EMPHASIS>(result) the result may be omitted.

<P> <EMPHASIS>(The PASS directive is also used to <EMPHASIS>(reverse-map) VMS
file specifications to the URL path format equivalent.\BOLD)

<P> <EMPHASIS>(An HTTP status-code message\BOLD) can be provided as a result.
The server then generates a response corresponding to that status code
containing the supplied message.  Status-code results should be enclosed in
one of single or double quotes, or curly braces.  See examples.  A
3<EMPHASIS>(nn) status results in a redirection response with the message text
comprising the location. Codes 4<EMPHASIS>(nn) and 5<EMPHASIS>(nn) result in
an error message.  Other code ranges (e.g. 0, 1<EMPHASIS>(nn), 2<EMPHASIS>(nn),
etc.) simply cause the connection to be immediately dropped, and can be used
for that purpose (i.e. no indication of why!)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(fail <EMPHASIS>(template)\BOLD) 

<P> If the URL path matches the template, prohibit access, processing no 
further rules.  The template path must be absolute (i.e. begin with
<QUOTE>(/)).

<ENDLIST>

<HEAD2>(REDIRECT Rule\head_map_rule_redirect)

<LIST>(NUMBERED)

<LE> <EMPHASIS>(redirect <EMPHASIS>(template) <EMPHASIS>(result)\BOLD)

<P> If the URL path matches the template, substitute the <EMPHASIS>(result) 
string for the path.  Process no further rules.  Redirection rules can provide
result URLs in four formats, each with a slightly different behaviour.

<LIST>(NUMBERED)

<LE> The <EMPHASIS>(result) can be a full URL
(<QUOTE>(http://host.domain/path/to/whatever)).  This is used to redirect
requests to a specific service, usually on a another host.

<COMMENT>(HTML=<P>)

<LE> If the scheme (e.g. <QUOTE>(http:)) is omitted the scheme of the
current request is substituted.  This allows HTTP requests to be transparently
redirected via HTTP and HTTPS (SSL) requests via HTTPS (e.g.
<QUOTE>(//host.domain/path/to/whatever), note the leading double-slash).

<COMMENT>(HTML=<P>)

<LE> In a similar fashion both the scheme and the host name may be omitted
(e.g. <QUOTE>(///path/to/whatever), note the leading triple-slash).  The server
then substitutes the appropriate request scheme and host name before returning
the redirection to the client.

<COMMENT>(HTML=<P>)

<LE> If the scheme is provided but no host component the current request's
host infomation is substituted and the redirection made using that (e.g.
<QUOTE>(https:///secure/path/to/whatever).  This effectively allows a request
to be redirected from standard to SSL, or from SSL to standard HTTP on the same
server. 

<COMMENT>(HTML=<P>)

<LE> Alternatively, it may be just a path (<QUOTE>(/path/to/whatever), a
single leading slash), which will cause the server to internally generate an
entire new request structure to process the new path (i.e. request redirection
is not returned to the client).

<ENDLIST>

<ENDLIST>

<HEAD2>(USER Rule\head_map_rule_user)

<P> The USER rule maps a VMS user account default device and directory (i.e.
<EMPHASIS>(home) directory) into a request path.  That is, the  base location
for the request is obtained from the VMS systems SYSUAF file.  This is usually
invoked by a request path in the form <QUOTE>(/~username/), see
<REFERENCE>(head_user_dirs) for more detailed information.

<LIST>(NUMBERED)

<LE> <EMPHASIS>(user <EMPHASIS>(template) <EMPHASIS>(result)\BOLD)

<P> If the path matches the template then the result is substituted, with the
following conditions.  At least one wildcard must be present.  The first
wildcard in the result substitutes the username's home directory into the path
(in place of the <QUOTE>(~username)).  Any subsequent wildcard(s) substitute
corresponding part(s) of the original path.

<P> If the user DANIEL's default device and directory were

<CODE_EXAMPLE>
  USER$DISK:[DANIEL]
<ENDCODE_EXAMPLE>

<CP> the following rule

<CODE_EXAMPLE>
  user /~*/* /*/www/*
<ENDCODE_EXAMPLE>

<CP> would result in the following path being mapped and used

<CODE_EXAMPLE>
  /user$disk/daniel/www/
<ENDCODE_EXAMPLE>

<ENDLIST>

<NOTE>
Accounts that possess SYSPRV, are CAPTIVE, have been DISUSERED or that have
expired passwords will not be mapped.  A <QUOTE>(directory not found) error
report is returned.
<ENDNOTE>

<HEAD2>(EXEC/UXEC and SCRIPT, Script Mapping Rules\head_map_rule_exec_script)

<P> Also see <QUOTE>(Scripting Environment) document for further information.

<P> The EXEC/UXEC and SCRIPT directives have the <EMPHASIS>(variants
EXEC+/UXEC+ and SCRIPT+\BOLD). These  behave in exactly the same fashion and
simply mark the rule as representing a CGIplus script environment.

<P> The EXEC/UXEC rules maps script <EMPHASIS>(directories\BOLD).

<P> The SCRIPT rules maps script <EMPHASIS>(file names\BOLD). It behaves a
little differently to the EXEC rule, essentially supplying in a single rule the
effect of a MAP then an EXEC rule. 

<P> Both rules must have a <EMPHASIS>(template) and <EMPHASIS>(result), and 
both must end in a wildcard asterisk.  The placement of the wildcards and the 
subsequent functionality is slightly different however.   Both template
and result paths must be absolute (i.e. begin with <QUOTE>(/)).

<LIST>(NUMBERED)

<LE> <EMPHASIS>(exec <EMPHASIS>(template result)\BOLD) 

<P> The EXEC rule requires the <EMPHASIS>(template)'s asterisk to immediately
follow the slash terminating the directory specification containing the
scripts. The script name follows immediately as part of the wildcard-matched
string. For example:

<CODE_EXAMPLE>
  exec /htbin/* /ht_root/script/*
<ENDCODE_EXAMPLE>

<P> If the URL path matches the template, the result, including the first
slash-terminated part of the wildcard-matched section, becomes the URL format
physical VMS file specification the script to be executed. What remains of the
original URL path is used to create the path information. Process no further
rules. 

<P> Hence, the EXEC rule will match multiple script specifications without
further rules, the script name being supplied with the URL path. Hence any
script (i.e. procedure, executable) in the specified directory is accessable,
a possible security concern if script management is distributed.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(exec <EMPHASIS>(template (run-time-environment)result)\BOLD) 

<P> A variation on the <QUOTE>(exec) rules allows a Run-Time Environment (RTE)
to be mapped.  An RTE is a persistant scripting environment not unlike CGIplus. 
The essential difference is an RTE provides an environment in which a variety
of scripts can be run.  It is often an interpreter, such as Perl, where the
advantages of persistance (reduced response latency and system impact) are
available.  For more information on RTEs and how they operate see the

<COMMENT>(HTML=
<A HREF="/ht_root/doc/scripting/">WASD Scripting Environment</A>
)

<COMMENT>(HTML/OFF)
<QUOTE>(WASD Scripting Environment)
<COMMENT>(HTML/ON) 

document.

<P> The RTE executable is specified in parentheses prefixed to the mapping
result, as show in this example:

<CODE_EXAMPLE>
  exec /pl-bin/* (cgi-bin:[0000000]perlrte.exe)/ht_root/src/perl/*
<ENDCODE_EXAMPLE>

<LE> <EMPHASIS>(script <EMPHASIS>(template result)\BOLD) 

<P> The SCRIPT rule requires the <EMPHASIS>(template)'s asterisk to
immediately follow the <EMPHASIS>(unique string) identifying the script in the
URL path. The wildcard-matched string is the following path, and supplied to
the script. For example: 

<CODE_EXAMPLE>
  script /conan* /ht_root/script/conan*
<ENDCODE_EXAMPLE>

<P> If the URL path matches the template, the result becomes the URL format
physical VMS file specification for the DCL procedure of the script to be
executed (the default file extension of <QUOTE>(.COM) is not required). What
remains of the original URL path is used to create the path information.
Process no further rules. 

<NOTE>
The wildcard asterisk is best located immediately after the unique script 
identifier. In this way there does not need to be any path supplied with the 
script.  If even a slash follows the script identifier it may be mapped into a 
file specification that may or may not be meaningful to the script.
<ENDNOTE> 

<P> Hence, the SCRIPT rule will match only the script specified in the
<EMPHASIS>(result), making for finely-granular scripting at the expense of a
rule for each script thus specified. It also implies that only the script name
need precede any other path information.

<P> It may be thought of as a more efficient implementation of the equivalent 
functionlity using two CERN rules, as illustrated in the following example:

<CODE_EXAMPLE>
  map /conan* /script/conan*
  exec /cgi-bin/* /cgi-bin/*
<ENDCODE_EXAMPLE>

<LE> <EMPHASIS>(uxec <EMPHASIS>(template result)\BOLD) 

<P> The UXEC rule is an analog to the EXEC rule, except it is used to map user
scripts.  It requires two mapping asterisks, the first for the username, the
second for the script name. It must be used in conjunction with a SET
<EMPHASIS>(script=as=~) rule. For example:

<CODE_EXAMPLE>
  SET   /~*/www/cgi-bin/*  script=as=~
  UXEC  /~*/cgi-bin/*  /*/www/cgi-bin/*
<ENDCODE_EXAMPLE>

<P> For further information see <REFERENCE>(head_user_scripts) and the
<QUOTE>(Scripting Overview, Introduction).

<ENDLIST>

<HEAD>(Script Location\head_map_rule_exec_dir)

<P> It is conventional to locate script images in HT_ROOT:[AXP] or
HT_ROOT:[VAX] (depending on the platform), and procedures, etc. in
HT_ROOT:[SCRIPT] or  HT_ROOT:[SCRIPT_LOCAL].  These multiple directories are
accessable via the single search list logical CGI-BIN.

<P> Script files can be located elsewhere, either subdirectories of
HT_ROOT:[SCRIPT_LOCAL] or in an area completely outside of the HT_ROOT tree. 
Two approaches are available.

<LIST>(NUMBERED)

<COMMENT>(HTML=<P>)

<LE> Modify the search list CGI-BIN to include the additional directories.

<COMMENT>(HTML=<P>)

<LE> Use mapping rules to make the script accessable.  This can be done by
using the EXEC or SCRIPT rule to specify the directory directly as in these
examples

<CODE_EXAMPLE>
  exec /mycgi-bin/* /site_local_scripts/bin/*
  script /myscript* /web/myscripts/bin/myscript.exe*
<ENDCODE_EXAMPLE>

<CP> or by using the MAP rules to make a hierarchy of script locations obvious
and accessable, as in this example

<CODE_EXAMPLE>
  map /cgi-bin/myscripts/* /cgi-bin_myscripts/* 
  exec /cgi-bin_myscripts/* /web/myscripts/bin/*
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD2>(SET Rule\head_set_rules)

<P> The SET rule does not change the mapping of a path, it just sets one or
more characteristics against that path that affect the subsequent processing
in some way. It is a general purpose rule that conveniently allows the
administrator to tell the server to process requests with particular paths in
some ad hoc and generally useful fashion. Most SET parameters are single
keywords that act as boolean switches on the request, some require parameter
strings. Multiple space-separated parameters may be set against against the one
path in a single SET statement.

<LIST>(NUMBERED)

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(AUTHONCE, NOAUTHONCE -\BOLD)
If a request path contains both a script component and a resource component by
default the WASD server makes sure both parts are authorized before allowing
access (see <REFERENCE>(chapter_authorization)).  This can be disabled using
this path setting.  When this is done only the original request path undergoes
authorization.
<QUOTE>(authONCE).

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(CACHE, NOCACHE -\BOLD)
The default is to cache files (when caching is enabled). NOCACHE sets files in
this path as not to be stored in the file cache. A subsequent CACHE will again
permit caching, allowing smaller path hierarchies to be cached within larger
ones that are not.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(CGIPREFIX -\BOLD)
CGI environment variable names are by default prefixed with <QUOTE>(WWW_). 
This may be changed on a per-path basis  using this SET rule.  To remove the
prefix altogether for selected scripts use <QUOTE>(CGIprefix=).

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(CHARSET -\BOLD)
This setting allows overriding of the server default ([CharsetDefault]
configuration parameter) content-type character set (in the response header)
for text files (plain and HTML).  A string is required as in the following
example, <QUOTE>(charset=ISO-8859-5).

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(CONTENT -\BOLD)
The content-type of a file is normally determined by the file's type
(extension). This setting allows files matching the template to be returned
with the specified content-type.  The content-type must be specified as a
parameter, e.g. <QUOTE>(content=application/binary).

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(EXPIRED, NOEXPIRED -\BOLD)
This setting allows files in the specified paths to be sent pre-expired. The
browser should always then reload them whenever accessed.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(INDEX -\BOLD)
This setting provides the <QUOTE>(Index of) (directory listing) format string
for directory paths matching the template.  It uses the same formatting as can
be supplied with a URL and overrides any query string passed via any URL.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(LOG, NOLOG -\BOLD)
When server access logging is enabled the default is to log all requests. The
NOLOG setting suppresses logging for requests involving the specified path
template.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(MAPONCE, NOMAPONCE -\BOLD)
Normally, when a script has been identified during mapping, the resultant path
information is also mapped in a second pass. This can be suppressed by SETting
the path as MAPONCE.  The resultant path is then given to the script without
further processing.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(PROFILE, NOPROFILE -\BOLD)
When using the server /PROFILE qualifier enable or disable the authentication
profile when assessing access for a specific path.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(REPORT -\BOLD)
This setting allows error and other server-generated reports for any specified
path to changed between <EMPHASIS>(detailed) and <EMPHASIS>(basic) (see
<REFERENCE>(head_error_reporting_basic)).  Use <QUOTE>(report=BASIC) and
<QUOTE>(report=DETAILED).

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(ODS-5, ODS-2 -\BOLD) The ODS-5 setting is used to indicate that
a particular path maps to files on an ODS-5 volume and so the names may comply
to extended specifications.  This changes the way file names are processed,
including for example the replacement of invalid RMS characters (see
immediately below).  The ODS-2 setting is basically redundant, because if a
path is not indicated as being ODS-5 it is assumed to be ODS-2.  This can be
used for clarity in the mapping rules if required.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(RMSCHAR -\BOLD) 
This setting applies to ODS-2 paths (the default) only.  Paths SET as ODS-5 do
not have this applied. During rule mapping of a path to a VMS file
specification, if an RMS-invalid character (e.g. <QUOTE>(+)) or syntax (e.g.
multiple periods) is encountered  a dollar symbol is substituted in an attempt
to make it acceptable. This setting provides an alternate substitution
character.  Any general RMS-valid character may be specified (e.g.
alpha-numeric, '$', '-' or '_', although the latter three are probably the only
REAL choices).  A single character is required as in the following example,
<QUOTE>(RMSchar=_).

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(SCRIPT=AS= -\BOLD)
For non-server account scripting this rule allows the user account to be either
explicitly specified or substituted through the use of the tilde character
<QUOTE>(~) or the dollar <QUOTE>($).  For further detail see the
<QUOTE>(Scripting Overview, Introduction).

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(SCRIPT=[FIND<VBAR>NOFIND] -\BOLD)
By default the server always confirms the existance and accessability of a
script file by searching for it before attempting to activate it.  If it does
not exsist it reports an error.  It may be possible a Run-Time Environment
(RTE) may require to access it's own script file via a mechanism available only
to itself.  The server script search may be disabled by SETting the path as
<EMPHASIS>(nofind), for example <QUOTE>(script=nofind).  The script path and
filename is directly passed to the RTE for it to process and activate.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(SSI -\BOLD)
SSI documents cannot contain privileged directives (e.g. <LITERAL>(<--#exec
... -->) unless owned by SYSTEM ([1,4]) or are in path set as allowing these
directives.  Use SSI=priv to enable this, SSI=nopriv to disable. 
<EMPHASIS>(Caution:\BOLD) these SSI directives are quite powerful, use great
care when allowing any particular document author or authors to use them.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(SSLCGI=<EMPHASIS>(string) -\BOLD)
Enables and sets the type of CGI variables used to represent a Secure
Sockets Layer (SSL) CGI variables.

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)
<LE> <QUOTE>(SSLCGI=none) disables the facility
<LE> <QUOTE>(SSLCGI=Apache_mod_SSL) provides Apache mod_ssl style variables
<LE> <QUOTE>(SSLCGI=Purveyor) provides Purveyor style variables
<ENDLIST>

<P> When enabling these variables it is advised to increase the HTTPD$CONFIG
[BufferSizeDclCommand] and [BufferSizeCgiPlusIn] directives by approximately
2048.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(STMLF, NOSTMLF -\BOLD)
Specify files to be automatically converted to Stream-LF format. The default is
to ignore conversion. STMLF allows selected paths to be converted. See
<REFERENCE>(head_perf_record_format).

<ENDLIST>

<P> Of course, as with all mapping rules, paths containing file types
(extensions) may be specified so it is quite easy to apply settings to
particular groups of files.  Multiple settings may be made against the one
path, merely separate set directives from each other with white-space. If a
setting string is required to contain white-space enclose the string with
single or double quotes, or curly brackets.  The following example gives a
small selection of potential uses.

<CODE_EXAMPLE>
  # examples of SET rule usage
  # --------------------------
  # disable caching for selected paths
  set /ht_root/src/* NOcache
  set /sys$common/* NOcache
  # enable stream-LF conversion in selected directory trees
  set /web/* stmlf
  set /ht_root/* stmlf
  # respond with Cyrillic character set(s) from relevant directories
  set /*/8859-5/* charset=ISO-8859-5
  set /*/koi8-r/* charset=KOI8-R
  # the Sun Java tutorial when UNZIPped contains underscores for invalid characters
  set /vms/java/tutorial/* RMSchar=_
  # if a request has "/plain-text/" in it's path then ALWAYS return as plain-text!
  set /*/plain-text/* content=text/plain
  map /*/plain-text/* /*/*
  # same for "/binary/"
  set /*/binary/* content=text/plain
  map /*/binary/* /*/*
  # indicate extended file specifications on this path
  set /Documents/* ODS-5
  pass /Documents/* /ods5_device/Documents/*
  # disable server script search for this RTE
  set /onerte/*  script=nofind
  exec /onerte/* (CGI-BIN:[000000]ONERTE.EXE)/ht_root/src/one/*
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<HEAD1>(Rule Interpretation\head_map_rule_interp)

<P> The rules are scanned from first towards last, until a matching PASS, EXEC,
SCRIPT, FAIL, REDIRECT, UXEC or USER rule is encountered, when processing
ceases and final substitution occurs. Mapped rules substitute the
<EMPHASIS>(template) with the <EMPHASIS>(result) and continue to the next rule. 

<P> Use of wildcards in <EMPHASIS>(template) and <EMPHASIS>(result):

<LIST>(UNNUMBERED)

<LE> The <EMPHASIS>(template\BOLD) may contain one or more asterisk
(<QUOTE>(*)) wildcard symbols. These match zero or more characters up until
the character following the wildcard (or end-of-string). If no wildcard is
present then the path must match the <EMPHASIS>(template) exactly. 

<COMMENT>(HTML=<P>)

<LE> The <EMPHASIS>(result\BOLD) may contain one or more asterisk (<QUOTE>(*))
wildcard symbols. It must not contain more wildcards than the
<EMPHASIS>(template). The <EMPHASIS>(result) wildcards are expanded to replace
the matching characters of the respective <EMPHASIS>(template) wildcards.
Characters represented by wildcards in the <EMPHASIS>(template) not
represented by a corresponding wildcard in the <EMPHASIS>(result) are ignored.
Non-wildcard <EMPHASIS>(result) characters are directly inserted in
reconstructed path. Non-wildcard characters in the <EMPHASIS>(template) are
ignored. If the <EMPHASIS>(result) contains no wildcards it completely
replaces the URL path. 

<ENDLIST>

<HEAD>(Virtual Servers\head_map_rule_virtual)

<P> As described in <REFERENCE>(head_virtual_services) virtual service syntax
may be used with mapping rules to selectively apply rules to one specific
service. If virtual services are configured rule interpretation sees only
rules common to all services and those specific to it's own service (host
address and port). In all other aspects rule interpretation applies as
described above.

<COMMENT>(....................................................................)

<HEAD1>(Mapping Examples\head_mapping_examples)

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The example
<A HREF="/ht_root/example/httpd$map.conf">mapping rule file</A> for the WASD
HTTP server can be viewed.
)

<COMMENT>(HTML/OFF)
<P> The example mapping rule file for the WASD HTTP server can be viewed.
<P><BOX>(online hypertext link)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<HEAD>(Example of <EMPHASIS>(Map\BOLD) Rule\head_example_map)

<P> The <EMPHASIS>(result) string of these rules may or may not correspond to 
to a VMS physical file system path.  Either way the resulting rule is further 
processed before passing or failing. 

<LIST>(NUMBERED)

<LE> The following example shows a path
<QUOTE>(/web/unix/shells/c) being mapped to
<QUOTE>(/web/software/unix/scripts/c), with this 
being used to process further rules. 

<CODE_EXAMPLE>
  map /web/unix/* /web/software/unix/*
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(Examples of <EMPHASIS>(Pass\BOLD) Rule\head_example_pass)

<P> The <EMPHASIS>(result) string of these rules should correspond to to a VMS 
physical file path. 

<LIST>(NUMBERED)

<LE> This example shows a path <QUOTE>(/web/rts/home.html) being mapped to
<QUOTE>(/user$rts/web/home.html), and this returned as the mapped path.

<CODE_EXAMPLE>
  pass /web/rts/* /user$rts/web/*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> This maps a path <QUOTE>(/icon/bhts/dir.gif) to
<QUOTE>(/web/icon/bhts/dir.gif), and this returned as the mapped path.

<CODE_EXAMPLE>
  pass /icon/bhts/* /web/icon/bhts/*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> This example illustrates HTTP status code mapping. Each of these does
basically the same thing, just using one of the three possible delimiters
according to the characters required in the message. The server generates a
403 response with has as it's text the following message. (Also see the
conditional mapping examples.)

<CODE_EXAMPLE>
  pass /private/* "403 Can't go in there!"
  pass /private/* '403 "/private/" is off-limits!'
  pass /private/* {403 Can't go into "/private/"}
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(Examples of <EMPHASIS>(Fail\BOLD) Rule\head_example_fail)

<LIST>(NUMBERED)

<LE> If a URL path <QUOTE>(/web/private/home.html) is being mapped the path
would immediately be failed.

<CODE_EXAMPLE>
  fail /web/private/*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> To ensure all access fails, other than that explicitly passed, this entry 
should be included the the rules. 

<CODE_EXAMPLE>
  fail /*
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(Examples of <EMPHASIS>(Exec\BOLD) and <EMPHASIS>(Script\BOLD) Rules
\head_example_exec)

<LIST>(NUMBERED)

<LE> If a URL path <QUOTE>(/htbin/ismap/web/example.conf) is being mapped the
<QUOTE>(/ht_root/script/) must be the URL format equivalent of the physical
VMS specification for the directory locating the script DCL procedure. The
<QUOTE>(/web/example.conf) that followed the <QUOTE>(/htbin/ismap) in the
original URL becomes the translated path for the script.

<CODE_EXAMPLE>
  exec /cgi-bin/* /cgi-bin/*
<ENDCODE_EXAMPLE>

<LE> If a URL path <QUOTE>(/pl-bin/example/this/directory/and-file.txt) is
being mapped the script name and filename become <QUOTE>(/pl-bin/example) and
<QUOTE>(HT_ROOT:[SRC.PERL]EXAMPLE.PL) respectively, the path information and
translated become <QUOTE>(/this/directory/and-file.txt) and
<QUOTE>(THIS:[DIRECTORY]AND-FILE.TXT), and the interpreter (run-time
environment) activated to interpret the script is CGI-BIN:[000000]PERLRTE.EXE.

<CODE_EXAMPLE>
  exec /pl-bin/* (cgi-bin:[000000]perlrte.exe)/ht_root/src/perl/*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> If a URL path <QUOTE>(/conan/web/example.hlb) is being 
mapped the <QUOTE>(/ht_root/script/conan) must be the URL format equivalent of 
the physical VMS specification for the DCL procedure.  The 
<QUOTE>(/web/example.hlb) that followed the 
<QUOTE>(/conan/) in the original URL becomes the translated path 
for the script.

<CODE_EXAMPLE>
  script /conan* /ht_root/script/conan*
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(Example of <EMPHASIS>(Redirect\BOLD) Rule\head_example_redirect)

<LIST>(NUMBERED)

<LE> If a URL path <QUOTE>(/AnotherGroup/this/that/other.html) is 
being mapped the URL would be redirected to
<QUOTE>(http://host/this/that/other.html)

<CODE_EXAMPLE>
  redirect /AnotherGroup/* http://host/group/*
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(....................................................................)

<HEAD1>(Virtual Servers\head_mapping_virtual)

<P> As described in <REFERENCE>(head_virtual_services), virtual service syntax
may be used with mapping rules to selectively apply rules to one specific
service.  This example provides the essentials of using this syntax.  Note
that service-specific and service-common rules may be mixed in any order
allowing common mappings (e.g. for scripting) to be shared.

<CODE_EXAMPLE>
  # a mapping rule example of virtual servers
  [[alpha.wasd.dsto.defence.gov.au:80]]
  # ALPHA is the only service allowing access to VMS help directory
  pass /sys$common/syshlp/*
  [[beta.wasd.dsto.defence.gov.au:80]]
  # good stuff is only available from BETA
  pass /good-stuff/*
  # BETA has it's own error report format, the others share one
  pass /errorreport /ht_root/local/errorreportalpha.shtml  
  [[gamma.wasd.dsto.defence.gov.au:80]]
  # gamma responds with documents using the Cyrillic character set
  set /* charset=ISO-8859-5
  [[*]]
  # common file and script mappings
  exec /cgi-bin/* /cgi-bin/*
  exec+ /cgiplus-bin/* /cgi-bin/*
  script+ /help/* /cgiplus-bin/conan/*
  pass /errorreport /ht_root/local/errorreport.shtml  
  # now the base directories for all documents
  [[alpha.wasd.dsto.defence.gov.au:80]]
  /* /web/alpha/*
  [[beta.wasd.dsto.defence.gov.au:80]]
  /* /web/beta/*
  [[gamma.wasd.dsto.defence.gov.au:80]]
  /* /web/gamma/*
  [[*]]
  # catch-all rule (just in case :^)
  pass /* /web/*
<ENDCODE_EXAMPLE>

<P> The server administration menu WATCH report (see
<REFERENCE>(head_server_reports)) provides the capability to view the rule
databse as well as rule mapping during actual request processing, using the
WATCH facility.

<COMMENT>(....................................................................)

<HEAD1>(Conditional Mapping\head_mapping_conditional)

<P> The purpose of <EMPHASIS>(conditional mapping) is to <EMPHASIS>(apply\BOLD)
rules only after certain criteria other than the initial path match are met. 
These criteria serve to create conditional mapping rules, and were introduced
in version 4.4.

<P><EMPHASIS>(THIS OFFERS A POWERFUL TOOL TO THE SERVER ADMINISTRATOR!\BOLD)

<P> Conditional mapping can be applied on the following criteria:

<LIST>(UNNUMBERED)

<LE> authenticated remote user
<LE> client internet address
<LE> browser-accepted languages
<LE> browser-accepted character sets
<LE> browser-accepted content-types 
<LE> browser identification string
<LE> cookie data
<LE> host and port specified in request header
<LE> HTTP method (GET, POST, etc.)
<LE> proxy/gateway host(s) request forwarded by
<LE> refering page
<LE> request scheme (protocol <HELLIPSIS> <QUOTE>(http:) or <QUOTE>(https:))
<LE> query string
<LE> server name
<LE> server port

<ENDLIST>

<P> Conditionals must follow the rule and are delimited by <QUOTE>([) and
<QUOTE>(]). Multiple, space-separated conditions may be included
within one <QUOTE>([...]). This behaves as a logical OR (i.e. the condition
only needs one matched to be true). Multiple <QUOTE>([...]) conditionals may be
included against a rule. These act as a logical AND (i.e. all must have at
least one condition matched).  If a condition begins with a <QUOTE>(!) it
acts as a negation operator (i.e. matched strings result in a false condition,
unmatched strings in a true condition). The result of an entire conditional may
also be negated by prefixing the <QUOTE>([) with a <QUOTE>(!).

<P> If a conditional, or set of conditionals, is not met the rule is completely
ignored.

<P> Matching is done by simple, case-insensitive, string comparison, using
the wildcards <QUOTE>(*), matching one or more characters, and <QUOTE>(%),
matching any single character.

<P> White-space (spaces and TABs), wildcards and the delimiting <QUOTE>([) and
<QUOTE>(]), are forbidden characters and cannot be used within condition
matching strings, nor can they be encoded for inclusion in any way (for
simplicity and speed of processing). These characters are uncommon in the
information being matched against, but if one does occur then <QUOTE>(match) it
using a single character wildcard (<QUOTE>(%)).

<P> While conditionals are powerful adjuncts to <EMPHASIS>(smart) serving they
do add significant overhead to rule mapping and should be used with this in
mind.

<HEAD>(Conditionals\head_conditionals)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(ac: -\BOLD) browser-accepted content types
(<QUOTE>(Accept:) request header field)
<LE> <EMPHASIS>(al: -\BOLD) browser-accepted languages
(<QUOTE>(Accept-Language:) request header field)
<LE> <EMPHASIS>(as: -\BOLD) browser-accepted character sets
(<QUOTE>(Accept-Charset:) request header field)
<LE> <EMPHASIS>(ck: -\BOLD) cookie data
(<QUOTE>(Cookie:) request header field)
<LE> <EMPHASIS>(fo: -\BOLD) request forwarded by proxy/gateway host(s)
(<QUOTE>(Forwarded:) request header field)
<LE> <EMPHASIS>(ho: -\BOLD) browser host internet name or address
<LE> <EMPHASIS>(hm: -\BOLD) browser host internet address compare to
dotted-decimal network and mask specification
<LE> <EMPHASIS>(me: -\BOLD) request HTTP method
<LE> <EMPHASIS>(qs: -\BOLD) query string
<LE> <EMPHASIS>(rf: -\BOLD) refering page
(<QUOTE>(Referer:) request header field)
<LE> <EMPHASIS>(ru: -\BOLD) authenticated remote user name
<LE> <EMPHASIS>(sc: -\BOLD) request <EMPHASIS>(scheme) (protocol),
<QUOTE>(http), and if SSL is in use <QUOTE>(https) (see
<REFERENCE>(chapter_ssl))
<LE> <EMPHASIS>(sn: -\BOLD) server name
<LE> <EMPHASIS>(sp: -\BOLD) server port
<LE> <EMPHASIS>(ua: -\BOLD) browser
(<QUOTE>(User-Agent:) request header field)
<LE> <EMPHASIS>(vs: -\BOLD) virtual host and port request directed to
(<QUOTE>(Host:) request header field)

<ENDLIST>

<HEAD>(Examples\head_conditionals_examples)

<NOTE>
It is possible to <EMPHASIS>(spoof) (impersonate) internet host addresses. 
Therefore any controls applied using host name/address information cannot be
used for authorization purposes in the strictest sense of the term.
<ENDNOTE>

<LIST>(NUMBERED)

<LE> The following example shows a rule being applied only if the client host
is within a particular subnet.  This is being used to provide a
<QUOTE>(private) home page to those in the subnet while others get a
<QUOTE>(public) page by the second rule.

<CODE_EXAMPLE>
  pass / /web/internal/ [ho:131.185.250.*]
  pass / /web/
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> This is a similar example to the above, but showing multiple host
specifications and specifically excluding one particular host using the
negation operator <QUOTE>(!). This could be read as <EMPHASIS>(pass if ((host
OR host) AND (not host))).    

<CODE_EXAMPLE>
  pass / /web/internal/ [ho:*.fred.com ho:*.george.com] [!ho:you.fred.com]
  pass / /web/
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The next example shows how to prevent browsing of a particular tree except
from specified host addresses.

<CODE_EXAMPLE>
  pass /web/internal/* /web/SorryNoAccess.html [!ho:131.185.250.*]
  pass /web/internal/*
<ENDCODE_EXAMPLE>

<P> This could be used to prevent browsing of the server configuration files
(an alternative to this sort of approach is to use the authorization file, see
<REFERENCE>(chapter_authorization)).

<CODE_EXAMPLE>
  pass /ht_root/local/* /web/SorryNoAccess.html [!ho:131.185.250.201]
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> This example performs much the same task as the previous one, but uses
whole conditional negation to prevent browsing of a particular tree except from
specified addresses (as well as using the continuation character to provide a
more easily comprehended layout <HELLIPSIS> note the trailing spaces as
required).  This could be read as <EMPHASIS>(pass if not (host OR host OR
host)).

<CODE_EXAMPLE>
  pass /web/internal/* /web/SorryNoAccess.html \
  ![\
  ho:131.185.250.* \
  ho:131.185.251.* \
  ho:131.185.45.1 \
  ho:ws2.wasd.dsto.gov.au\
  ]
  pass /web/internal/*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> This example demonstrates mapping pages according to geography or language
preference (it's a bit contrived, but <HELLIPSIS>)

<CODE_EXAMPLE>
  pass /doc/* /web/doc/french/* [ho:*.fr al:fr]
  pass /doc/* /web/doc/swedish/* [ho:*.se al:se]
  pass /doc/* /web/doc/english/*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> How to exclude specific browsers from your site (how many times have we
seen this!)

<CODE_EXAMPLE>
  # I had to pick on a well-known acronym, no offence Bill!
  pass /* /web/NoThankYou.html [ua:*MSIE*]
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> This example allows excluding certain requests from specific addresses.
This could be read as <EMPHASIS>(pass if ((method is POST) AND (not host))).

<CODE_EXAMPLE>
  pass /* /web/NotAllowed.html [me:POST] [!ho:*.my.net]
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The following illustrates using the server name and/or server port to
conditionally map servers executing on clustered nodes using the same
configuration file, or for multi-homed/multi-ported hosts. Distinct home pages
are maintained for each system, and on BETA two servers execute, one on port
8000 that may only be used by those within the specified network address
range.

<CODE_EXAMPLE>
  pass / /web/welcome_to_Alpha.html [sn:alpha.*]
  pass / /web/welcome_to_Beta.html [sn:beta.*] [sp:80]
  pass /* /sorry_no_access.html [sn:beta.*] [sp:8000] [!ho:*.my.sub.net]
  pass / /web/welcome_to_Beta_private.html [sn:beta.*] [sp:8000]
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> Each of these three do basically the same thing, just using the three
possible delimiters according to the characters required in the message.
The server generates a 403 response with has as it's text the following
message.

<CODE_EXAMPLE>
  pass /private/* "403 Can't go in there!" [!ho:my.host.name]
  pass /private/* '403 "/private/" is off-limits!' [!ho:my.host.name]
  pass /private/* {403 Can't go into "/private/"} [!ho:my.host.name]
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> This example illustrates the use of a host network mask, the <QUOTE>(HM:)
conditional.

<CODE_EXAMPLE>
  pass /private/* "403 Can't go in there!" [!hm:131.185.250.128/255.255.255.192]
<ENDCODE_EXAMPLE>

<P> The mask is a dotted-decimal network address, a slash, then a
dotted-decimal mask.  This example shows a 6 bit subnet.  Network mask
conditionals operate by bitwise-ANDing the client host address with the mask,
bitwise-ANDing the network address supplied with the mask, then comparing the
two results for equality.  Using the above example the host 131.185.250.250
would be accepted, but 131.185.250.50 would be rejected.

<ENDLIST>

<P> <EMPHASIS>(Note that rule processing for any particular path may be
checked using the WATCH facility from the server administration menu.
See <REFERENCE>(chapter_watch) for details.\BOLD)

<COMMENT>(....................................................................)

<HEAD1>(Mapping User Directories (<EMPHASIS>(tilde) character (<QUOTE>(~)))
\head_user_dirs) 

<P> The convention for specifying user web areas is <QUOTE>(/~username/).  The
basic idea is that the user's web-available file-space is mapped into the
request in place of the tilde and username.

<HEAD2>(Using The SYSUAF\head_user_dirs_sysuaf)

<P> The USER rule maps a VMS user account default device and directory (i.e.
<EMPHASIS>(home) directory) into a request path (see
<REFERENCE>(head_map_rule_user)).  That is, the base location for the request
is obtained from the VMS systems SYSUAF file.  A user's home directory
information is cached, to reduce load on the authorization databases.  As this
information is usually quite static there is no timeout period on such
information (although it may be flushed to make room for other user's).  Cache
contents is include in the Mapping Rules Report (see
<REFERENCE>(head_server_reports)) and is implicitly flushed when the server's
rules are reloaded (see <REFERENCE>(head_server_action)).

<P> The following is a typical usage of the rule.

<CODE_EXAMPLE>
  USER  /~*/*  /*/www/*
<ENDCODE_EXAMPLE>

<P> Note the <QUOTE>(/www) subdirectory component.  It is <EMPHASIS>(stongly
recommended\BOLD) that users never be mapped into their top-level, but into a
web-specific subdirectory.  This effectively <QUOTE>(sandboxes) Web access to
that subdirectory hierarchy, allowing the user privacy elsewhere in the home
area.

<P> To accomodate request user paths that do not incorporate a trailing
delimiter after the username the following redirect may be used to cause the
browser to re-request with a more appropriate path (make sure it follows the
USER rule).

<CODE_EXAMPLE>
  REDIRECT  /~*  ///~*/
<ENDCODE_EXAMPLE>

<P> WASD also <QUOTE>(reverse maps) VMS specifications into paths and so
requires additional rules to provide these mappings.  (Reverse mapping is
required during directory listings and error reporting.)  For the continuing
example the following rules would be required (and in the stated order).

<CODE_EXAMPLE>
  USER  /~*/*  /*/www/*
  REDIRECT  /~*  ///~*/
  PASS  /~*/*  /user$disk/*/www/*
<ENDCODE_EXAMPLE>

<P> Where user home directories are spread over multiple devices (physical or
concealed logical) a reverse-mapping rule would be required for each. Consider
the following situation, where user directories are distributed across these
devices (concealed logicals)

<CODE_EXAMPLE>
  USER$GROUP1:
  USER$GROUP2:
  USER$GROUP2:
  USER$OTHER:
<ENDCODE_EXAMPLE>

<P> This would require the following mapping rules (in the stated order).

<CODE_EXAMPLE>
  USER  /~*/*  /*/www/
  PASS  /~*/*  /user$group1/*/www/*
  PASS  /~*/*  /user$group2/*/www/*
  PASS  /~*/*  /user$group3/*/www/*
  PASS  /~*/*  /user$other/*/www/*
<ENDCODE_EXAMPLE>

<P> Accounts with a search list as a default device (e.g. SYS$SYSROOT) present
particular complications in this schema and should be avoided.

<NOTE>
Accounts that possess SYSPRV, are CAPTIVE, have been DISUSERED or that have
expired passwords will not be mapped.  A <QUOTE>(directory not found) error
report is returned.  This error was chosen to make it to make more difficult 
to <EMPHASIS>(probe) the authorization environment, determining whether
accounts exist or not.
<ENDNOTE>

<P> Of course vanilla mapping rules may be used to provide for special
cases.  For instance, if there is requirement for a particular, privileged
account to have a user mapping that could be provided as in the following
(rather exagerated) example.

<CODE_EXAMPLE>
  PASS  /~system/*  /sys$common/sysmgr/www/*
  USER  /~*/*  /*/www/
  PASS  /~*/*  /user$disk/*/www/*
<ENDCODE_EXAMPLE>

<HEAD>(User Account Scripting\head_user_scripts)

<P> In some situations it may be desirable to allow the average Web user to
experiment with or implement scripts.  With WASD 7.1 and later, and VMS V6.2
and later, this is possible.  Detached scripting must be enabled, the /PERSONA
startup qualifier used, and appropriate mapping rules in place.  If the SET
<QUOTE>(script=as=) mapping rule specifies a tilde character then for a
user request the mapped SYSUAF username is substituted.

<P> The following example shows the essentials of setting up a user environment
where access to a subdirectory in the user's home directory, [.WWW] with
script's located in a subdirectory of that, [.WWW.CGI-BIN].

<CODE_EXAMPLE> 
  SET   /~*/www/cgi-bin/*  script=as=~
  UXEC  /~*/cgi-bin/*  /*/www/cgi-bin/*
  USER  /~*/*  /*/www/*
  REDIRECT  /~*  /~*/
  PASS  /~*/*  /dka0/users/*/*
<ENDCODE_EXAMPLE> 

<P> For more detailed information see the <QUOTE>(Scripting Overview,
Introduction).

<HEAD2>(Without Using The SYSUAF\head_user_dirs_without)

<P>
<NOTE>(Deprecated and Discouraged)
There are now <QUOTE>(better) approaches to achieving the same functionality
as described in this section.  This documentation is retained only for
reference by older site configurations.
<ENDNOTE>

<P> The server is also able to map user directories using the same mechanisms
as for  any other.  No reference needs to be made to the SYSUAF, user support
can be accomplished via a combination of mapping rule and logical name.  This
approach relies on a correspondance between the username and the home
directory name.  Hence users are made known by the HTTPd using the name of
their top-level directory.  User scripts can also be supported using WASD's
DECnet scripting environment.

<P> The <QUOTE>(PASS) rule provides a wildcard representation of users'
directory paths. As part of this mapping a subdirectory specifically for the
hypertext data should always be included. <EMPHASIS>(Never\BOLD) map users'
top-level directories. For instance if a user's account home directory was
located in the area USER$DISK:[DANIEL] the following rule would potentially
allow the user DANIEL to provide web documents from the home subdirectory
[.WWW] (if the user has created it) using the accompanying URL: 

<CODE_EXAMPLE>
  pass /~*/* /user$disk/*/www/*

  http://host/~daniel/
<ENDCODE_EXAMPLE>

<P> It is <EMPHASIS>(recommended\BOLD) that a separate logical name be created 
for locating user directories.  This helps hide the internal organisation of 
the file system.  The following logical name definition and mapping rule 
illustrate this point. 

<CODE_EXAMPLE>
  $ DEFINE /SYSTEM /EXEC /TRANSLATION=CONCEALED WWW_USER device:[USER.]

  pass /~*/* /www_user/*/www/*
<ENDCODE_EXAMPLE>

<P> Where users are grouped into different areas of the file system a logical 
search list may be defined. 

<CODE_EXAMPLE>
  $ DEFINE /SYSTEM /EXEC /TRANSLATION=CONCEALED -
           WWW_USER -
           DISK1:[GROUP1.], -
           DISK1:[GROUP2.], -
           DISK2:[GROUP3.], -
           DISK2:[GROUP4.]
    
  pass /~*/* /www_user/*/www/*
<ENDCODE_EXAMPLE>

<P> As logical search lists have specific uses and some complications (e.g.
when creating files) this is the only use for them recommended with this
server, although it is specifically coded to allow for search lists in document
specifications.

<P> If only a subset of all users are to be provided with WWW publishing 
access either their account directories can be individually mapped (best used 
only with a small number) or a separate area of the file system be provided 
for this purpose and specifically mapped as user space. 

<P> Of course, user mapping is amenable to all other rule processing so it is 
a simple matter to redirect or otherwise process user paths.  For instance, 
the published username does not need to, or need to continue to, correspond 
to any real user area, or the user's actual name or home area: 

<CODE_EXAMPLE>
  redirect /~doej/* http://a.nother.host/~doej/*
  pass /~doej/* /www/messages/deceased.html
  pass /~danielm/* /special$www$area/danielm/*
  pass /~Mark.Daniel/* /user$disk/danielm/www/*
  pass /~*/* /www_user/*/www/*
<ENDCODE_EXAMPLE>

<P> A user directory is always presented as a top-level directory (i.e. no 
parent directory is shown), although any subdirectory tree is accesssable by 
default.

<COMMENT>(--------------------------------------------------------------------)
