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

<CHAPTER>(Server Configuration\chapter_config)

<P> Server configuration basically concerns itself with 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.

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

<HEAD1>(Site Organisation\head_organ_site)

<P> Here are a few <QUOTE>(Mother's Truths) about site organisation.  These are
only basic and obvious suggestions (after a little step back from the sometimes
initially overwhelming feeling of <QUOTE>(what do I do now with this brand new
toy?)).  There are lots of general documents of Web site organisation and
design that are applicable to all server environments.  Above all, bring your
own software system design experience to the Web-specific environment, it's not
all that different to any other transaction-based, user-interactive environment.

<P> It is recommended that the server distribution tree and any document and
other Web-specific data areas be kept separate and distinct. The former in
HT_ROOT:[000000], the latter perhaps in something like WEB:[000000]. This
logical device could be provided with the following DCL introduced into the
site or server startup procedures:

<CODE_EXAMPLE>
  $ DEFINE /SYSTEM /TRANSLATION=CONCEALED WEB DSA811:[WEB.]
<ENDCODE_EXAMPLE>

<P> Note that logical device names like this need not appear in in the
structure of the Web site.  The root of the Web-accessable path can be
concealed using a final mapping rule similar to the following

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

<CP> which simply defaults <EMPHASIS>(anything else) to that physical area.  Of
course if that <EMPHASIS>(anything else) needs to exist then it must be located
in that physical area.

<P> Mapping rules are the tools used to build a logical structure to a site
from the  physical area, perhaps multiple areas, used to house the associated
files. The logical organisation of served data is largely hierarchical,
organised under the Web-server path root, and is achieved via two mechanisms.

<LIST>(NUMBERED)

<LE> The natural tree structure provided by a hierarchical file system.

<LE> The logical hierarchy possible using rules within the mapping file to 
place disparate physical areas into a single logical structure.

<ENDLIST>

<P> Physically distinct areas are used for good physical reasons (e.g. the
area can best be hosted on a task-local disk), for historical reasons (e.g.
the area existed before any Web environment existed) or for reasons of
convenience (e.g. lets put this where access controls already allow the
maintainers to manage it). 

<HEAD>(Guidelines\head_data_area_guidelines)

<P> There are <UNDERLINE>(no good reasons) for having site-specific documents
integrated  with the package directory structure.  All site-served files should
be located in an autonomous, dedicated area or areas.  The only reason to place
script files into HT_ROOT:[CGI-BIN] or HT_ROOT:[<emphasis>(architecture)_BIN]
is that the script script is traditionally accessable via a /cgi-bin/ path or
that the site is a small and/or low usage environment where this directory is
conveniently available for the few extra scripts being made available.

<P> For any significant site (size that as best suits your perception), or for
when a specific software system or systems is being built or exists and it is
being <QUOTE>(Web-ified), design that software system as you would be any
other.  That is place the documentation in one directory are, executables and
support procedures in their own, management files in another, data in yet
another area, etc.  Then make those portions that are required to be accessable
via the Web interface accessable via the logical associations afforded through
the use of the server's mapping rules (<REFERENCE>(chapter_mapping_rule)).  Of
course existing areas that are to be now made available via the Web can be
mapped in the same way.  This includes the active components - executable
scripts.  There is no reason (apart from historical) why the /cgi-bin/ path
should be used to activate scripts associated with a dedicated software system. 
Use a specific and unique path for scripts associated with each such system.

<P> When making a directory structure available via the Web care must be taken
that only the portions required to be accessed can be.  Other areas should or
must not be accessable.  The server process can only access files that are
world-accessable, it is specifically granted access via VMS protection
mechanisms (e.g. ACLs), or that the individual SYSUAF-authorized accessor can
access and which have specifically  been made available via server
authorization rules.  Use the recommendations in
<REFERENCE>(head_config_secure_package) as guidlines when designing your own
site's protections and permissions.

<HEAD>(Document Root\head_data_area_root)

<P> A particular area of the file system may be specified as the
<EMPHASIS>(root) of a particular (virtual) sites documents.  This is done using
the HTTPD$MAP SET <EMPHASIS>(map=root=<LITERAL>(<string>)) mapping rule.  After
this rule is applied all subsequent rules have the specified string prefixed to
mapped strings before file-system resolution.

<P> For example, the following HTTPD$MAP rule set

<CODE_EXAMPLE>
  [[the.virtual.site:*]]

  pass /*/-/* /ht_root/runtime/*/*
  /ht_root/* /ht_root/*

  set * map=root=/dka0/the_site

  exec /cgi-bin/* /cgi-bin/*
  pass /* /*
  fail *
<ENDCODE_EXAMPLE>

<CP> when applied to the following request URLs results in the described
mappings being applied.

<CODE_EXAMPLE>
  http://the.virtual.site/doc/example.txt
<ENDCODE_EXAMPLE>

<CP> access to the document represented by file

<CODE_EXAMPLE>
  DKA0:[THE_SITE.DOC]EXAMPLE.TXT
<ENDCODE_EXAMPLE>

<P> With the request for a directory icon using

<CODE_EXAMPLE>
  http://the.virtual.site/-/httpd/file.gif
<ENDCODE_EXAMPLE>

<CP> access to the image represented by file

<CODE_EXAMPLE>
  HT_ROOT:[RUNTIME.HTTPD]FILE.GIF
<ENDCODE_EXAMPLE>

<P> And a request for a script using

<CODE_EXAMPLE>
  http://the.virtual.site/cgi-bin/example.php
<ENDCODE_EXAMPLE>

<CP> activation of the script represented by the file

<CODE_EXAMPLE>
  DKA0:[THE_SITE.CGI-BIN]EXAMPLE.PHP
<ENDCODE_EXAMPLE>

<P> Care must be taken in getting the sequence of mapping rules correct for
access to non-site resources before actually setting the document root which
then ties every other resource to that root.

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

<HEAD1>(Server Instances\head_config_instances)

The term <EMPHASIS>(instance) is used by WASD to describe an autonomous server
process.  WASD will support multiple servers running on a single system, alone
or in combination with multiple servers running across a cluster.  When
multiple instances are configured on a single system they cooperate to
distribute the request load between themselves and share certain essential
resources such as accounting and authorization information.

<NOTE>(WARNING)
Versions earlier than Compaq TCP/IP Services v5.3 and some TCPware
v5.<EMPHASIS>(n) (at  least)  have a problem with socket listen queuing that
can cause services to <QUOTE>(hang) (should this happen just restart the
server).  Ensure you have the requisite version/ECO/patch installed before
activating multiple instances on production systems!
<ENDNOTE>

<HEAD>(VMS Clustering Comparison\head_config_instances_compare)

<P> The approach WASD has used in providing multiple instance serving may be
compared in many ways to VMS clustering.

<P> A cluster is often described as a loosely-coupled, distributed operating
environment where autonomous processors can join, process and leave (even fail)
independently, participating in a single management domain and communicating
with one another for the purposes of resource sharing and high availability.

<P> Similarly WASD instances run in autonomous, detached processes (across one
or more systems in a cluster) using a common configuration and management
interface, aware of the presence and activity of other instances (via the
Distributed Lock Manager and shared memory), sharing processing load and
providing rolling restart and automatic <QUOTE>(fail-through) as required.

<HEAD>(Load Sharing\head_config_instances_load)

<P> On a multi-CPU system there are performance advantages to having processing
available for scheduling on each.  WASD employs AST (I/O) based processing and
was not originally designed to support VMS kernel threading.  Benchmarking has
shown this to be quite fast and efficient even when compared to a
kernel-threaded server (OSU) across 2 CPUs.  The advantage of multiple CPUs for
a single multi-threaded server also diminishes where a site frequently
activates scripts for processing.  These of course (potentially) require a CPU
each for processing.  Where a system has many CPUs (and to a lesser extent with
only two and few script activations) WASD's single-process, AST-driven design
would scale more poorly.  Running multiple WASD instances addresses this.

<P> <EMPHASIS>(Of course load sharing is not the only advantage to multiple
instances <HELLIPSIS>\BOLD)

<HEAD>(Restart\head_config_instances_restart)

<P> When multiple WASD instances are executing on a node and a restart is
initiated only one process shuts down at a time.  Others remain available for
requests until the one restarting is again fully ready to process them itself,
at which point the next commences restart.  This has been termed a
<EMPHASIS>(rolling restart).  Such behaviour allows server reconfiguration on a
busy site without even a small loss of availability.

<HEAD>(Fail-Through\head_config_instances_fail)

<P> When multiple instances are executing on a node and one of these exits for
some reason (resource exhaustion, bugcheck, etc.) the other(s) will continue
to process requests.  Of course requests in-progress by the particular instance
at the time of instance failure are disconnected (this contrasts with the
rolling restart behaviour described above).  If the former process has
actually exited (in contrast to just the image) a new server process will
automatically be created after a few seconds.

<P> The term <EMPHASIS>(fail-through) is used rather than <EMPHASIS>(failover)
because one server does not commence processing as another ceases.  All servers
are constantly active with those remaining immediately and automatically taking
all requests in the absence any one (or more) of them.

<HEAD>(Considerations\head_config_instances_cost)

<P> Of course <QUOTE>(there is no such thing as a free lunch) and supporting
multiple instances is no exception to this rule.  To coordinate activity
between and access to shared resources, multiple instances use low-level
mutexes and the VMS Distributed Lock Manager (DLM).  This does add some system
overhead and a little latency to request processing, however as the benchmarks
indicate (<REFERENCE>(chapter_server_perf)) increases in overall request
throughput on a multi-CPU system easily offset these costs.  On single CPU
systems the advantages of rolling restart and fail-through need to be assessed
against the small cost on a per-site basis.  It is to be expected many low
activity sites  will not require multiple instances to be active at all.

<P> When managing multiple instances on a single node it is important to
consider each process will receive a request in round-robin distribution and
that this needs to be considered when debugging scripts, using the Server
Administration page and the likes of WATCH, etc.

<HEAD>(Configuration\head_config_instances_config)

<P> If not explicitly configured only one instance is created.  The
configuration directive [InstanceMax] allows multiple instances to be
specified (<REFERENCE>(chapter_config_directives)).  When this is set to an
integer that many instances are created and maintained.  If set to
<QUOTE>(CPU) then one instance per system CPU is created.  If set to
<QUOTE>(CPU-<EMPHASIS>(integer)) then one instance for all but one CPU is
created, etc.  The current limit on instances is eight, although this is
somewhat arbitrary.  As with all requests, Server Administration page access
is automatically shared between instances.  There are occasions when consistent
access to a single instance is desirable.  This is provided via an
<EMPHASIS>(admin service) (<REFERENCE>(chapter_service_directives)).

<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). There is no design limitation on the number of
these services that WASD will concurrently support.  Virtual services offer
versatile and powerful multi-site capabilities using the one system and
server.  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
(<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 (<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.

<NOTE>
There is a difference when specifying virtual services during service creation
and when using them to apply mapping, etc.  When creating a service the
scheme (or protocol, e.g. <QUOTE>(http:), <QUOTE>(https:)) needs to be
specified so the server can apply the correct protocol to connections accepted
at that service.  Once a service is created however, it becomes defined by the
host-name and port supplied when created.  Only one scheme (protocol) can be
supported on any one host-name/port instance and so it becomes unnecessary to
provide it with mapping rules, etc.  The server will complain in instances
where it is redundant.
<ENDNOTE>

<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>(Request Throttling\head_request_throttling)

<P> Request <QUOTE>(throttling) is a term adopted to describe controlling the
number of requests that can be processing against any specified path at any one
time.  Requests in excess of this value are First-In-First-Out (FIFO) queued,
up to an optional limit, waiting for a currently processing request to conclude
allowing the next queued request to resume processing.  This is primarily
intended to limit concurrent resource-intensive script execution but could be
applied to any resource path.  Here's one dictionary description.

<P><EMPHASIS>(
<EMPHASIS>(throttle n 1:\BOLD) a valve that regulates the supply of fuel to the
engine [syn: accelerator, throttle valve] <EMPHASIS>(2:\BOLD) a pedal that
controls the throttle valve; <QUOTE>(he stepped on the gas) [syn: accelerator,
accelerator  pedal, gas pedal, gas, gun] <EMPHASIS>(v 1:\BOLD) place limits on;
<QUOTE>(restrict the use of this parking lot) [syn: restrict, restrain,
trammel, limit, bound, confine] <EMPHASIS>(2:\BOLD) squeeze the throat of;
<QUOTE>(he tried to strangle his opponent) [syn: strangle, strangulate]
<EMPHASIS>(3:\BOLD) reduce the air supply; of carburetors [syn: choke]
)

<P> This is applied to a path (or paths) using the HTTPD$MAP mapping SET
THROTTLE= rule (<REFERENCE>(head_set_rules)).  The general format is

<CODE_EXAMPLE>
  set <EMPHASIS>(path) throttle=<EMPHASIS>(n1)[<EMPHASIS>(,n2,n3,n4,t/o1,t/o2)]
  set <EMPHASIS>(path) throttle=<EMPHASIS>(from)[<EMPHASIS>(,to,resume,busy,t/o-queue,t/o-busy)]
<ENDCODE_EXAMPLE>

<CP> where

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(n1) sets the number of concurrent requests before queuing
begins (the  number of processing requests becomes static and the number of
queued requests increases)

<LE> <EMPHASIS>(n2) is the concurrent requests before FIFO queuing begins,
meaning each new request is put onto the queue but at the same the first-in
request is taken off the queue for processing (the number of queued requests
becomes static and the number of processing requests increases)

<LE> <EMPHASIS>(n3) puts a limit on FIFO queuing (the number of queued requests
again increases and the number of processing requests becomes static)

<LE> <EMPHASIS>(n4) is an absolute limit for concurrent requests against the
path (a 503 <QUOTE>(server too busy) status is immediately generated)

<LE> <EMPHASIS>(t/o1) is the maximum period for queued requests before they are
processed (if not constrained by <EMPHASIS>(n3))

<LE> <EMPHASIS>(t/o2) is the maximum period for queued requests
before a 503 <QUOTE>(server too busy) response is returned, it begins
immediately or following the expiry of any <EMPHASIS>(t/o1)

<ENDLIST>

<P> One way to read a throttle rule is <QUOTE>(begin to <EMPHASIS>(throttle)
(queue) requests <EMPHASIS>(from) the n1 value up <EMPHASIS>(to) the n2 value,
after which the queue is FIFOed up to the n3 value when it
<EMPHASIS>(resume)s queuing-only, up until the <EMPHASIS>(busy) n4 value).

<P> Each integer represents the number of concurrent requests against the
throttle rule path.  Parameters not required may be specified as zero or
omitted in a comma-separated list.  The schema of the rule requires that each
successive parameter be larger than that preceding it.  This basic  consistency
check is performed when the rule is loaded.

<P> For any rule the possible maximum number of requests that can be
processed at any one time may be simply calculated through the addition of the
<EMPHASIS>(n1) value to the difference of the <EMPHASIS>(n3) and
<EMPHASIS>(n2) values (i.e. max = n1 + (n3 - n2)).  The maximum concurrently
queued as the difference of the <EMPHASIS>(n4) and the maximum concurrently
processed.

<P> A comprehensive throttle statistics report is available from the Server
Administration page (<REFERENCE>(chapter_server_admin)).

<HEAD>(Examples\head_request_throttle_examples)

<LIST>(NUMBERED)

<LE> <EMPHASIS>(throttle=10\BOLD)

<P> Requests up to 10 are concurrently processed.  When 10 is reached futher
requests are queued to server capacity.

<LE> <EMPHASIS>(throttle=10,20\BOLD)

<P> Concurrent requests to 10 are processed immediately.  From 11 to 20
requests  are queued.  After 20 all requests are queued but also result in a
request FIFOing off the queue to be processed (queue length is static, number
being processed increases to server capacity).

<LE> <EMPHASIS>(throttle=15,30,40\BOLD)

<P> Concurrent requests up to 15 are immediately processed.  Requests 16
through to  30 are queued, while 31 to 40 requests result in the new requests
being queued and waiting requests being FIFOed into processing.  Concurrent
requests from 41 onwards are again queued, in this scenario to server capacity.

<LE> <EMPHASIS>(throttle=10,20,30,40\BOLD)

<P> Concurrent requests up to 10 are immediately processed.  Requests 11
through  to 20 will be queued.  Concurrent requests from 21 to 30 are queued
too, but at the same time waiting requests are FIFOed from the queue (resulting
in 10 (n1) + 10 (n3-n2) = 20 being processed).  From 31 onwards requests are
just queued.  Up to 40 concurrent requests may be against the path before all
new requests are immediately returned with a 503 "busy" status.  With this
scenario no more than 20 can be concurrently processed with 20 concurrently
queued.

<LE> <EMPHASIS>(throttle=10,,,30\BOLD)

<P> Concurrent requests up to 10 are processed.  When 10 is reached requests
are  queued up to request 30.  When request 31 arrives it is immediately given
a 503 "busy" status.

<LE> <EMPHASIS>(throttle=10,20,30,40,00:02:00\BOLD)

<P> This is basically the same as scenario 4) but with a resume-on-timeout of
two  minutes.  If there are currently 15 (or 22 or 28) requests (n1 exceeded,
n3 still within limit) the queued requests will begin processing on timeout. 
Should there be 32 processing (n3 has reached limit) the request will continue
to sit in the queue.  The timeout would not be reset.

<LE> <EMPHASIS>(throttle=15,30,40,,,00:03:00\BOLD)

<P> This is basically the same as scenario 3) but with a busy-on-timeout of
three  minutes.  When the timeout expires the request is immediately dequeued
with a 503 "busy" status.

<ENDLIST>

<HEAD>(Mapping Reload\head_request_throttle_reload)

<P> Throttling is applied using mapping rules.  The set of these rules may be
changed within an executing server using map reload functionality.  This means
the number of, and/or  contents of, throttle rules may change during server
execution.  The throttle functionality needs to be independent of the the
mapping functionality (requests are processed independently of mapping rules
once the rules have been applied).  After a mapping reload the contents of the
throttle data structures may be at variance with the constraints currently
executing requests began processing under.

<P> This should have little deleterious effect.  The worst case is mis-applied
constraints on the execution limits of changed request paths, and slightly
confusing data in the Throttle Report.  This quickly passes as requests being
processed under the previous throttle constraints conclude and an entirely new
collection of requests created using the constraints of the currently loaded
rules are processed.

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

<HEAD1>(Client Concurrency\head_client_concurrency)

<P> The <QUOTE>(client_connect_gt:) mapping conditional
(<REFERENCE>(chapter_conditional)) attempts to allow some measurement of the
number of requests a particular client currently has being processed.  Using
this decision criterion appropriate request mapping for controlling the
additional requests can be undertaken.  It is not intended to provide 
fine-grained control over activities, rather just to prevent a single client
using an unreasonable proportion of the resources.

<P> For example.  If the number of requests from one particulat client looks
like it has got out of control (at the client end) then it becomes possible to
queue (throttle) or reject further requests.  In HTTPD$MAP

<CODE_EXAMPLE>
  if (client_connect_gt:15) set * throttle=15

  if (client_connect_gt:15) pass * "503 Exceeding your concurrency limit!"
<ENDCODE_EXAMPLE>

<P> While not completely foolproof it does offer some measure of control over
gross client concurrency abuse or error.

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

<HEAD1>(Content-Type Configuration\head_config_content_type)

<P> HTTP uses an 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.

<HEAD2>(Adding Content-Types\head_config_content_addtype)

<P> In common with most HTTP servers WASD uses a file's suffix (extension,
type, e.g. <QUOTE>(.HTML, <QUOTE>(.TXT), <QUOTE>(.GIF)) to identify the data
type within the file. The [AddType] directive is used during configuration to
bind a file type to a MIME content-type.  To make the server recognise and
return specific content-types these directives map file types to content-types.

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

<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).  If this
is not done the default icon specified by [AddDefaultIcon] is displayed.  If
that is not defined then 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> Mappings using [AddType] look like these.

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

<HEAD2>(MIME.TYPES\head_config_content_mimetypes)

<P> To allow the server to share content-type definitions with other MIME-aware
applications, and for WASD scripts to be able to perform their own mapping on a
shared understanding of MIME content it is possible to move the file suffix to
content-type mapping from a collection of [AddType]s in HTTPD$CONFIG to an
external file.  This file is usually named MIME.TYPES and is specified in
HTTPD$CONFIG using the [AddMimeTypesFile] directive.

<P> Mappings using MIME.TYPES look like these.

<CODE_EXAMPLE>
  # MIME type			Extension
  application/msword            doc
  application/octet-stream      bin dms lha lzh exe class
  application/oda               oda
  application/pdf               pdf
  application/postscript        ai eps ps
  application/rtf               rtf
<ENDCODE_EXAMPLE>

<P> A leading content-type is mapped to single or multiple file suffixes. 
A general MIME.TYPES file commonly has content-types listed with no
corresponding file suffix.  These are ignored by WASD.  Where a file suffix is
repeated during configuration the latter version completely supercedes the
former (with the Server Administration page showing an italicised and
struck-through content-type to help identify duplicates).

<P> To allow the configuration information used by the server to generate
directory listings with additional detail, WASD-specific extensions to the
standard MIME.TYPES format are provided.  These are <QUOTE>(hidden) in comment
structures so as not to interfere with non-WASD application use.  All begin
with a hash then an exclamation character (<QUOTE>(#!)) then another reserved
character indicating the purpose of the extension.  Existing comments are
unaffected provided the second character is anything but an exclamation mark!

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(#! file description\BOLD)
<LINE> A space reserved character indicates following free-form text, used as
the file type description displayed on the far right of directory listings.

<LE> <EMPHASIS>(#!/cgi-bin/script\BOLD)
<LINE> A forward-slash introduces an auto-script specification.  An auto-script
is automatically activated by the server to process and display a corresponding
file's contents.  These are sometimes refered to as <EMPHASIS>(presentation)
scripts.

<LE> <EMPHASIS>(#![<EMPHASIS>(alt)] /path/to/icon.gif\BOLD)
<LINE> A left-square-bracket is used for icon specifications.  These are
actually mapped against the following content-type, not file suffix, and so
only need to be specified once for each content-type in the file.  This behaves
in a similar fashion to [AddIcon], only the components are reversed.

<LE> <EMPHASIS>(#!!\BOLD)
<LINE> The two exclamation marks can be used to indicate a MIME type intended
for WASD only.  The can be ignored by non-WASD applications.

<LE> <EMPHASIS>(#!+\BOLD)
<LINE> An exclamation mark then a plus symbol indicates an FTP transfer mode
directive.  One of three characters may follow the plus.  An <QUOTE>(A)
indicates that this file type should be FTP transfered in ASCII mode.  An
<QUOTE>(I) or a <QUOTE>(B) indicates that this file type should be FTP
transfered in Image (binary) mode.

<LE> <EMPHASIS>(#!%\BOLD)
<LINE> A percentage is ignored by WASD.  This is reserved for local (non-WASD)
viewers.

<ENDLIST>

<P> These directives are placed <EMPHASIS>(following\BOLD) the MIME-type entry
they apply to.  An example of the contents of a MIME.TYPES file with various
WASD extensions.

<CODE_EXAMPLE>
  # MIME type			Extension
  application/msword            doc
  #! MS Word document
  #![DOC] /httpd/-/doc.gif
  application/octet-stream      bin dms lha lzh exe class
  #! binary content
  #![BIN] /httpd/-/binary.gif
  application/oda               oda
  application/pdf               pdf
  application/postscript        ai eps ps
  #! Adobe PostScript
  #![PS.] /httpd/-/postscript.gif
  #!+A
  application/rtf               rtf
  #! Rich Text Format
  #![RTF] /httpd/-/rtf.gif
  application/x-script          bks decw$bookshelf
  #! DEC Bookshelf
  #!/cgi-bin/hypershelf
  application/x-script          bkb decw$book
  #![BKR] /httpd/-/script.gif
  #! DEC Book
  #!/cgi-bin/hyperreader
<ENDCODE_EXAMPLE>

<P> Other reserved characters have been specified for development purposes but
are not (perhaps currently) employed by the HTTP server.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(#!<LITERAL>(<) html marked-up text\BOLD)
<LINE> A less-than symbol indicates HTML marked-up text.

<LE> <EMPHASIS>(#!# blah blah blah\BOLD)
<LINE> <EMPHASIS>(##! rhubarb rhubarb\BOLD)
<LINE> Two combinations of hash and exclamation characters provide for
WASD-specific comments.

<ENDLIST>

<HEAD2>(Unknown Content-Types\head_config_content_unknown)

<P> If a file type is not recognised (i.e. no [AddType] or [AddMimeTypesFile]
mapping 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.

<HEAD2>(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>(Language Variants\head_language_variants)

<P> Language-specific variants of a document may be configured to be served
automatically and transparently.  This is organized as a basic file and name
with language-specific variant indicated by an additional <QUOTE>(tag), one of
ISO language abbreviations used by the <QUOTE>(Accept-Language:) request
header field, e.g. <EMPHASIS>(en) for English, <EMPHASIS>(fr) for French,
<EMPHASIS>(de) for  German, <EMPHASIS>(ru) for Russian, etc.

<P> Two variants of the basic file specification are possible; file name (the
default) and file type.  Hence if the basic file name is EXAMPLE.HTML then
specifically German, English, French and Russian language versions in the
directory would be either

<CODE_EXAMPLE>
  EXAMPLE.HTML
  EXAMPLE_DE.HTML
  EXAMPLE_EN.HTML
  EXAMPLE_FR.HTML
  EXAMPLE_RU.HTML
<ENDCODE_EXAMPLE>

<CP> or

<CODE_EXAMPLE>
  EXAMPLE.HTML
  EXAMPLE.HTML_DE
  EXAMPLE.HTML_EN
  EXAMPLE.HTML_FR
  EXAMPLE.HTML_RU
<ENDCODE_EXAMPLE>

<P> A path must be explicitly SET using the <EMPHASIS>(accept=lang) mapping
rule as containing language variants.  As searching for variants is a
relatively expensive operation the rule(s) applying this functionality should
be carefully crafted.  The <EMPHASIS>(accept=lang) rule accepts an optional
default language representing the contents of the basic, untagged files.  This
provides an opportunity to more efficiently handle requests with a language
first preference matching that of the default.  In this case no variant search
is undertaken, the basic file is simply served.  The following example sets a
path to contain files with a default language of French and possibly containing
other language variants.

<CODE_EXAMPLE>
  set /web/doc/* accept=lang=(default=fr)
<ENDCODE_EXAMPLE>

<P> In this case the behaviour would be as follows.  With the default language
set to <QUOTE>(fr) a request's <QUOTE>(Accept-Language:) field is initially
processed to check if the first preference is for <QUOTE>(fr).  If it is then
there is no need for further accept language processing and the basic file is
returned as the response.  If not then the directory is searched for other
files matching the EXAMPLE_*.HTML specification.  All files  matching this
wildcard have the <QUOTE>(*) portion (e.g. <QUOTE>(EN), <QUOTE>(FR),
<QUOTE>(DE), <QUOTE>(RU)) added to a list of variants.  When the search is
complete this list is compared to the request's <QUOTE>(Accept-Language:)
list.  The first one to be matched has the contents of the corresponding file
returned.  If none are matched the default version would be returned.

<P> This example of the behaviour is based on the contents of the directory
described above.  A request that specifies

<CODE_EXAMPLE>
  Accept-Language: fr,de,en
<ENDCODE_EXAMPLE>

<CP> will have EXAMPLE.HTML returned (without having searched for any other
variants).  For a request specifying 

<CODE_EXAMPLE>
  Accept-Language: ru,en
<ENDCODE_EXAMPLE>

<CP> then the EXAMPLE_RU.HTML file is returned, and if no
<QUOTE>(Accept-Language:) is supplied with the request EXAMPLE.HTML would be
returned.  One or other file is always returned, with the default, non-language
file  always the fallback source of data.  If it does not exist and no other
language variant is selected the request returns a 404 file-not-found error.

<HEAD>(Content-Type\head_language_type)

<P> When using the <EMPHASIS>(accept=lang=(variant=type)) form of the rule
(i.e. the variant is placed on the file type rather than the default file name)
each possible file extension must also must have it's content-type made known
to the server.  Using the example above the variants would need to be
configured in a similar way to the following.

<CODE_EXAMPLE>
  [AddType]
  .HTML     "text/html; charset=ISO-8859-1"  HyperText Markup Language
  .HTML_DE  "text/html; charset=ISO-8859-1"  HTML (German)
  .HTML_EN  "text/html; charset=ISO-8859-1"  HTML (English)
  .HTML_FR  "text/html; charset=ISO-8859-1"  HTML (French)
  .HTML_RU  "text/html; charset=koi8-r"      HTML (Russian)
<ENDCODE_EXAMPLE>

<HEAD>(Non-Text Content\head_language_non_text)

<P> Normally only files with a content-type of <QUOTE>(text/..) are subject to
variant searching.  If the rule path includes a file type then those files
matching the rule are also variant-searched.  In this way images, audio files,
etc., may also have language-specific versions supplied transparently.  The
following illustrates this usage

<CODE_EXAMPLE>
  set /web/doc/*.jpg accept=lang=(default=fr)
  set /web/doc/*.wav accept=lang=(default=fr)
<ENDCODE_EXAMPLE>

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

<HEAD1>(Character Set Conversion\head_charset_conv)

<P> The default character set sent in the response header for text documents
(plain and HTML) is set using the [CharsetDefault] directive and/or the SET
charset mapping rule.  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.

<P> Document and CGI script output may be dynamically converted from one
character set to another using the standard VMS NCS conversion library.  The
[CharsetConvert] directive provides the server with character set aliases
(those that are for all requirements the same) and which NCS conversion
function may be used to convert one character set into another.

<CODE_EXAMPLE>
  document-charset  accept-charset[,accept-charset..] [NCS-function-name[=factor]]
<ENDCODE_EXAMPLE>

<P> When this directive is configured the server compares each text response's
character set (if any) to each of the directive's <EMPHASIS>(document charset)
string.  If it matches it then compares each of the <EMPHASIS>(accepted
charset) (if multiple) to the request <QUOTE>(Accept-Charset:) list of accepted
characters sets.

<P> At least one <EMPHASIS>(doc-charset) and one <EMPHASIS>(accept-charset)
must be present.  If only these two are present (i.e. no
<EMPHASIS>(NCS-conversion-function)) it indicates that the two character sets
are aliases (i.e. the same set of characters, different name) and no conversion
is necessary.

<P> If an <EMPHASIS>(NCS-conversion-function) is supplied it indicates that the
document <EMPHASIS>(doc-charset) can be converted to the request
<QUOTE>(Accept-Charset:) preference of  the <EMPHASIS>(accept-charset) using
the NCS conversion function name specified.

<P> A <EMPHASIS>(factor) parameter can be appended to the conversion function. 
Some conversion functions require more than one output byte to represent one
input byte for some characters.  The 'factor' is an integer between 1 and 4
indicating how much more buffer space may be required for the converted string. 
It works by allocating that many times more output buffer space than is
occupied by the input buffer.  If not specified it defaults to 1, or an output
buffer the same size as the input buffer.

<P> Multiple comma-separated <EMPHASIS>(accept-charset)s may be included as the
second component for either of the above behaviours, with each being matched
individually. Wildcard <QUOTE>(*) and <QUOTE>(%) may be used in the
<EMPHASIS>(doc-charset) and <EMPHASIS>(accept-charset) strings.

<CODE_EXAMPLE>
  [CharsetConvert]
  windows-1251 windows-1251,cp-1251
  windows-1251 koi8-r windows1251_to_koi8r
  koi8-r koi8-r,koi8
  koi8-r windows-1251,cp-1251 koi8r_to_windows1251
  koi8-r utf-8 koi8r_to_utf8=2
<ENDCODE_EXAMPLE>

<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> Customized error reports can be generated for all or selected HTTP status
status associated with errors reported by the server using the HTTPD$CONFIG
[ErrorReportPath] and HTTPD$SERVER [ServiceErrorReportPath] configuration
directives.  To explicitly handle all error reports specify the path to the
error reporting mechanism (see description below) as in the following example.

<CODE_EXAMPLE>
  [ErrorReportPath] /httpd/-/reporterror.shtml
<ENDCODE_EXAMPLE>

<P> To handle only selected error reports add the HTTP status codes following
the report path.  In this example only 403 and 404 errors are explicitly
handled, the rest remain server-generated.  This is particularly useful for
static error documents.

<CODE_EXAMPLE>
  [ErrorReportPath] /httpd/-/reporterror.shtml 403 404
<ENDCODE_EXAMPLE>

<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.  For SSI and
CGI script handlers 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.

<P> It is suggested with any use of this facility the reporting
document(s) be located somewhere local, probably HT_ROOT:[RUNTIME.HTTPD], and then
enabled by placing the appropriate path into the [ErrorReportPath]
configuration directive.

<CODE_EXAMPLE>
  [ErrorReportPath] /httpd/-/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 /httpd/-/alphareport.shtml
  [[beta.wasd.dsto.gov.au]]
  pass /errorreport.shtml /httpd/-/betareport.shtml
  [[gamma.wasd.dsto.gov.au]]
  pass /errorreport.shtml /httpd/-/gammareport.shtml
<ENDCODE_EXAMPLE>

<HEAD>(Using Static HTML Documents\head_error_reporting_html)

<P> Static HTML documents are a good choice for site-specific error messages. 
They are very low overhead and are easily customizable.  One per possible
response error status code is required.  When providing an 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 HTTP status code.  A file for each possible or configured code must then be
provided, in this example for 403 (authorization failure), 404 (resource not
found) and 502 (bad gateway/script).

<CODE_EXAMPLE>
  [ErrorReportPath] /httpd/-/reporterror!UL.html 403 404 502
<ENDCODE_EXAMPLE>

<P> This mapping will generate paths such as the following, and require the
three specified to respond to those errors.

<CODE_EXAMPLE>
  /httpd/-/reporterror403.html
  /httpd/-/reporterror404.html
  /httpd/-/reporterror502.html
<ENDCODE_EXAMPLE>

<HEAD>(Using an SSI Document\head_error_reporting_ssi)

<P> SSI documents provide the versatility of dynamic report generation for
but they do take  time and CPU for processing, and this may be a significant
consideration on busy sites.

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

<P>
<CENTER_LINE>(<EMPHASIS>(Error Variables\BOLD))
<TABLE>
<TABLE_SETUP>(2\20)
<TABLE_HEADS>(Variable\Description)

<TABLE_ROW>(ERROR_LINE\
The HTTPd source code line from where the error was generated.)

<TABLE_ROW>(ERROR_MODULE\
The HTTPd source code module corresponding to the line described above.)

<TABLE_ROW>(ERROR_REPORT\
A single HTML string providing a detailed error message.)

<TABLE_ROW>(ERROR_REPORT2\
A single HTML comment providing more detailed VMS error information if
available)

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

<TABLE_ROW>(ERROR_STATUS_CLASS\
Essentially the single hundreds digit from the status code (e.g. 4).)

<TABLE_ROW>(ERROR_STATUS_CODE\
The HTTP response status code representing the error (e.g. 404).)

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

<TABLE_ROW>(ERROR_STATUS_TEXT\
The HTTP response status code abbreviated meaning (e.g. <QUOTE>(Not Found)).)

<TABLE_ROW>(ERROR_STATUS_TYPE\
<QUOTE>(basic) or <QUOTE>(detailed).)

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

<ENDTABLE>

<HEAD>(Using a Script\head_error_reporting_script)

<P> It is also possible to report using a script.
The same error information is available via corresponding CGI variables.
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.

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

<HEAD1>(OPCOM Logging\head_opcom)

<P> Significant server events may be optionally displayed via a selected
operator's console and recorded in the operator log.  Various categories of
these events may be selectively enabled via HTTPD$CONFIG directives
(<REFERENCE>(chapter_config_directives)).

<LIST>(UNNUMBERED)

<LE> Server Administration page directives
<LE> authentication/authorization (e.g. failures)
<LE> CLI HTTPd control directives
<LE> HTTPd events (e.g. startup, exit, SSL private key password requests)
<LE> proxy file cache maintenance

<ENDLIST>

<P> Some significant server events are always logged to OPCOM if any one of the 
above categories is enabled.

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

<P> Where multiple access log files are generated with per-instance, per-period
and/or per-service logging (see below) these can be merged into single files
for administrative or archival purposes using the CALOGS utility
(<REFERENCE>(head_calogs)).

<P> The Quick-and-Dirty LOG STATisticS utility (<REFERENCE>(head_qdlogstats))
can be used to provide elementary ad hoc log analysis from the command-line
or CGI interface.

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

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

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

<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>
<CENTER_LINE>(<EMPHASIS>(A <QUOTE>(!) followed by\BOLD))
<TABLE>
<TABLE_SETUP>(2\10)
<TABLE_HEADS>(Characters\Description)
<TABLE_ROW>(AR\authentication realm (if any))
<TABLE_ROW>(AU\authenticated user name (if any))
<TABLE_ROW>(BB\bytes in body (excludes response header))
<TABLE_ROW>(BY\bytes in response (includes header))
<TABLE_ROW>(CA\client address)
<TABLE_ROW>(CN\client host name (or address if DNS lookup disabled))
<TABLE_ROW>(EM\request elapsed time in milliseconds)
<TABLE_ROW>(ES\request elapsed time in fractional seconds)
<TABLE_ROW>(ID\session track ID)
<TABLE_ROW>(ME\request method)
<TABLE_ROW>(PA\request path (not to be confused with <QUOTE>(RQ)))
<TABLE_ROW>(QS\request query string (if any))
<TABLE_ROW>(RF\referer (if any))
<TABLE_ROW>(RQ\complete request string (see below))
<TABLE_ROW>(RS\response status code)
<TABLE_ROW>(SN\server host name)
<TABLE_ROW>(SC\script name (if any))
<TABLE_ROW>(SM\request scheme (http: or https:))
<TABLE_ROW>(SP\server port)
<TABLE_ROW>(TC\request time (common log format))
<TABLE_ROW>(TG\request time (GMT))
<TABLE_ROW>(TV\request time (VMS format))
<TABLE_ROW>(UA\user agent)
<ENDTABLE>

<CENTER_LINE>(<EMPHASIS>(A <QUOTE>(<BACKSLASH>) followed by\BOLD))
<TABLE>
<TABLE_SETUP>(2\10)
<TABLE_HEADS>(Character\Description)
<TABLE_ROW>(0\a null character (used to define the empty field character))
<TABLE_ROW>(!\insert an <QUOTE>(!))
<TABLE_ROW>(<BACKSLASH>\insert a <QUOTE>(<BACKSLASH>))
<TABLE_ROW>(n\insert a newline)
<TABLE_ROW>(q\insert a quote (so that in DCL the quotes won't need escaping!))
<TABLE_ROW>(t\insert a TAB)
<ENDTABLE>

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

<NOTE>(<QUOTE>(PA) and <QUOTE>(RQ))
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.
<ENDNOTE>

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

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

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

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

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

<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 [LogFile] 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 (<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 Per-Instance\head_log_per_instance)

<P> To reduce physical disk activity, and thereby significantly improve
performance, the RMS characteristics of the logging stream are set to buffer
records for as long as possible and only write to disk when buffer space is
exhausted (a periodic flush ensures records from times of low activity are
written to disk).  However when multiple server processes (either in the case
of multiple instances on a single node, single instance on each of multiple
clustered  nodes, or a combination of the two) have the same log files open for
write then this buffering and defered write-to-disk is disabled by RMS, it
insisting that all records must be flushed to disk for correct serialization
and coherency.

<P> This introduces measuraable latency and a potentially significant
bottleneck to high-demand processing.  Note that it only becomes a real
issue under load.  Sites with a low load should not experience any impact.

<P> Sites that may be affected by this issue can revert to the original
buffered log stream by enabling the [LogPerInstance] configuration directive.
This ensures that each log stream has only one writer by creating a unique log
file for each instance process executing on the node and/or cluster.  It does
this by appending the node and process name to the file type.  This would
change the log name from something like

<CODE_EXAMPLE>
  HT_LOGS:131-185-250-202_80_ACCESS.LOG
<ENDCODE_EXAMPLE>

<CP> to, in the case of a two-instance single node,

<CODE_EXAMPLE>
  HT_LOGS:131-185-250-202_80_ACCESS.LOG_KLAATU_HTTPD-80
  HT_LOGS:131-185-250-202_80_ACCESS.LOG_KLAATU_HTTPE-80
<ENDCODE_EXAMPLE>

<P> <EMPHASIS>(Of course the number-of and naming-of log files is beginning to
become a little itimidating at this stage!\BOLD)  To assist with managing
this seeming plethora of access log files is the calogs utiltiy
(<REFERENCE>(head_calogs)), which allows multiple log files to be merged whilst
keeping the records in timestamp order.

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

<HEAD2>(Log Naming\head_log_naming)

<P> When per-period or per-service logging is enabled the access log file has a
specific 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 literal 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>

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

<CODE_EXAMPLE>
  HT_LOGS:131-185-250-202_80_ACCESS.LOG_KLAATU_HTTPD-80
  HT_LOGS:WASD-DSTO-DEFENCE-GOV-AU_80_ACCESS.LOG_KLAATU_HTTPD-80
  HT_LOGS:WASD_80_ACCESS.LOG_KLAATU_HTTPD-80
  HT_LOGS:131-185-250-202_80_19971013_ACCESS.LOG_KLAATU_HTTPD-80
  HT_LOGS:WASD-DSTO-DEFENCE-GO_80_19971013_ACCESS.LOG_KLAATU_HTTPD-80
  HT_LOGS:WASD_80_19971013_ACCESS.LOG_KLAATU_HTTPD-80
<ENDCODE_EXAMPLE>

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

<HEAD2>(Access Alert\head_log_alert)

<P> It is possible to mark a path as being of specific interest.  When this is
accessed by a request the server puts a message into the the server process log
and perhaps of greater immediate utility the increase in alert hits is detected
by HTTPDMON and this (optionally) provides an audible alert allowing immediate
attention.  This is enabled on a per-path basis using the SET mapping rule. 
Variations on the basic rule allow some control over when the alert is
generated.

<P>

<LIST>(SIMPLE)                
<LE> ALERT - at the conclusion of the request
<LE> ALERT=MAP - immediately after mapping (early)
<LE> ALERT=AUTH - when (any) authorization has been performed
<LE> ALERT=END - at the conclusion of the request (default)
<LE> ALERT=<EMPHASIS>(integer) - see below
<LE> NOALERT - suppress alert for this path
<ENDLIST>

<P> The special case ALERT=<EMPHASIS>(integer) allows a path to be alerted if
the final response HTTP status is the same as the integer specified (e.g. 501,
404) or within the category specified (599, 499).

<HEAD1>(Include File Directive\head_config_directives_include)

<P> WASD uses multiple configuration files for a server and it's site, each one
providing for a different functional aspect <HELLIPSIS> configuration, virtual
services, path mapping, authorization, etc.  Generally these configuration
files are <QUOTE>(flat), with all required directives included in a single
file.  This  provides a simple and straight-forward approach suitable for most
sites and allows for the provision of Server Administration page online
configuration of several aspects.

<P> It is also possible to build site configurations by including the contents
of referenced files.  This may provide a structure and flexibility not possible
using the flat-file approach.  All WASD configuration files allow the use of an
[IncludeFile] directive.  This takes a VMS file specification parameter.  The
file's contents are then loaded and processed as if part of the parent
configuration file.  These included files are allowed to be nested to a depth
of two (i.e. the configuration file can include a file which may then include
another file).

<P> The following is an example used to build up the mapping rules for four
virtual services supported on the one server.

<CODE_EXAMPLE>
  # HTTPD$MAP

  [[alpha.site.com]]
  [IncludeFile]  HT_ROOT:[LOCAL]MAP_ALPHA_80.CONF
  [[alpha.site.com:443]]
  [IncludeFile]  HT_ROOT:[LOCAL]MAP_ALPHA_443.CONF

  [[beta.site.com]]
  [IncludeFile]  HT_ROOT:[LOCAL]MAP_BETA_80.CONF
  [[beta.site.com:443]]
  [IncludeFile]  HT_ROOT:[LOCAL]MAP_BETA_443.CONF

  [[*]]
  [IncludeFile]  HT_ROOT:[LOCAL]MAP_COMMON.CONF
<ENDCODE_EXAMPLE>

<NOTE>
Such configurations cannot be managed using Server Administration page
interfaces.  Files containing [IncludeFile] directives are noted during server
startup and if an Server Administration page configuration interface is
accessed where this would be a problem an explanatory message and warning is
provided.  A configuration <EMPHASIS>(can still be saved) but the resulting
configuration will be a flat-file representation of the server configuration,
not the original hierarchical one.
<ENDNOTE>

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

<CHAPTER>(<QUOTE>(Securing) The Site\chapter_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 copy
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 configurations can be made 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.

<P> The example configuration files contain a fairly restrictive set of
directives.  When relaxing these recommendations keep in mind that the more
information available about the underlying structure of the site the more
potential for subversion.  Do not enable functionality that contributes nothing
to the fundamental usefulness of the site, or that has the real potential to
compromise any given site.  This section refers to configuration directives
discussed in more detail in later chapters.

<P> It is established wisdom that the only secure computing system is one
with no users and no access, that system security is inversely proportional to
system usability, and that making something idiot-proof results in only idiots
using it.  So there are some trade-offs but <HELLIPSIS> 

<NOTE>(don't think it can't happen to you!)

A systematic investigation of installed WASD packages by well-known IT
professional Jean-loup Gailly during September 2002 revealed a couple of
significant implementation flaws which compounded by notable instances of
sloppy management practices on two public sites resulted in site compromise
(one was mine).

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

<LIST>(UNNUMBERED)

<COMMENT>(HTML=
<LI><A HREF="/ht_root/doc/misc/wasd_advisory_020925.txt">
HT_ROOT:[DOC.MISC]WASD_ADVISORY_020925.TXT</A>)

<COMMENT>(HTML/OFF)
<LE>HT_ROOT:[DOC.MISC]WASD_ADVISORY_020925.TXT
<COMMENT>(HTML/ON)

<COMMENT>(HTML=
<P><LI><A HREF="http://online.securityfocus.com/archive/1/293229">
http://online.securityfocus.com/archive/1/293229</A>)

<COMMENT>(HTML/OFF)
<LE>http://online.securityfocus.com/archive/1/293229
<COMMENT>(HTML/ON)
     
<ENDLIST>

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

<P> This research has resulted in these server flaws being closed and package
security considerations being extensively reviewed.  As a result WASD v8.1
is much more resistent to such penetration than previous releases (and slightly
less easy to use, but that's one of those trade-offs).  My assessment would be
that if Gailly did not find it then it wasn't there to find!

<P> Of course any given site's security is a function of the underlying
package's security profile, with the site's implementation of that, AND other
considerations such as local authorization and script implementations.  Pay
particular and ongoing attention to site security and integrity.

<ENDNOTE>

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

<HEAD1>(Recommended Package Security\head_config_secure_package)

<P> The following table provides recommended file protection settings for
package top-level directories.  Subdirectories share their parents' settings. 
The package tree is owned by the SYSTEM account.  Directories with world READ
access have no ACLs.  Other directories, not accessable to the world, but
sometimes having other degress of access to one or more accounts always have
rights identifiers (see below) and associated ACLs to control directory access,
and to propagate required access to files created beneath them. The server
selectively enables SYSPRV to provide access to some of these areas (e.g. for
log creation).

<P> Some pre-version 8.1 directories are not included in this table.  These are
not significant in versions from 8.1 onwards and may be deleted.  They can
continue to exist however and the security procedures described below ensure
that they comply to the general post-8.1 security model.  The file access
permissions indicated below are for directory contents.  The directory files
themselves have settings appropriate for content access.

<P>
<CENTER_LINE>(<EMPHASIS>(Package Access\BOLD))
<TABLE>
<TABLE_SETUP>(4\15\10\10)
<TABLE_HEADS>(Directory\Access<LINE>World\Access<LINE>Other\Description)
<TABLE_ROW>([AXP-BIN]\none\script:RE\Alpha executable script files)
<TABLE_ROW>([AXP]\none\none\Alpha build and utility area)
<TABLE_ROW>([CGI-BIN]\none\script:RE\architecture-neutral script files)
<TABLE_ROW>([DOC]\read\(world)\package documentation)
<TABLE_ROW>([EXAMPLE]\read\(world)\package examples)
<TABLE_ROW>([EXERCISE]\read\(world)\package test files)
<TABLE_ROW>([HTTP$NOBODY]\none\script:RWED\scripting account default home area)
<TABLE_ROW>([HTTP$SERVER]\none\server:RWED\server account default home area)
<TABLE_ROW>([IA64-BIN]\none\script:RE\IA64 executable script files)
<TABLE_ROW>([IA64]\none\none\IA64 build and utility area)
<TABLE_ROW>([INSTALL]\read\(world)\installation, update and secuity procedures)
<TABLE_ROW>([LOCAL]\none\none\site configuration files)
<TABLE_ROW>([LOG]\none\none\site access logs)
<TABLE_ROW>([LOG_SERVER]\none\server:RWED\server process (SYS$OUTPUT) logs)
<TABLE_ROW>([RUNTIME]\read\(world)\graphics, help files, etc.)
<TABLE_ROW>([SCRATCH]\none\script:RWED\working file space for scripts)
<TABLE_ROW>([SCRIPT]\none\none\example architecture-neutral scripts)
<TABLE_ROW>([SRC]\none\(world)\package source files)
<TABLE_ROW>([STARTUP]\none\server:RE\package startup procedures)
<TABLE_ROW>([VAX-BIN]\none\script:RE\VAX executable script files)
<TABLE_ROW>([VAX]\none\none\VAX build and utility area)
<ENDTABLE>

<P> It is recommended site-specific directories have settings applied
appropriate to their function in comparison to similar package directories. 
See below for tools to assist in this.

<P> Three rights identifiers provide selective access control to
the directory tree.  Identifiers were used to allow maximum flexibility for a
site in allowing required accounts access to either execute the server or
execute scripts.  Non-default account names only need to be granted one of
these identifiers to be provided with that role's access.  Installation, update
and/or security utilities create and maintain these identifiers appropriately.

<P>
<CENTER_LINE>(<EMPHASIS>(Rights Identifiers\BOLD))
<TABLE>
<TABLE_SETUP>(2\15)
<TABLE_HEADS>(Identifier\Description)
<TABLE_ROW>(WASD_HTTP_SERVER\Indicates the default server account.)
<TABLE_ROW>(WASD_HTTP_NOBODY\Indicates the default scripting account.)
<TABLE_ROW>(WASD_IGNORE_THIS\Looked for by the SECHAN utility to avoid it
changing security on site-specific files.)
<ENDTABLE>

<P> These rights identifiers are applied to directories and files to provide
the required level of access.  The following example shows the security setting
of the top-level CGI-BIN.DIR and one of it content files.

<CODE_EXAMPLE>
  $ DIRECTORY /SECURITY CGI-BIN.DIR

  Directory HT_ROOT:[000000]

  CGI-BIN.DIR;1        [SYSTEM]                         (RWED,RWED,,)
            (IDENTIFIER=WASD_HTTP_SERVER,ACCESS=EXECUTE)
            (IDENTIFIER=WASD_HTTP_NOBODY,ACCESS=EXECUTE)
            (IDENTIFIER=*,ACCESS=NONE)
            (IDENTIFIER=WASD_HTTP_NOBODY,OPTIONS=DEFAULT,ACCESS=READ+EXECUTE)
            (IDENTIFIER=*,OPTIONS=DEFAULT,ACCESS=NONE)
            (DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD:)

  Total of 1 file.
  $ DIRECTORY /SECURITY [CGI-BIN]CGI_SYMBOLS.COM

  Directory HT_ROOT:[CGI-BIN]

  CGI_SYMBOLS.COM;1    [SYSTEM]                         (RWED,RWED,,)
            (IDENTIFIER=WASD_HTTP_NOBODY,ACCESS=READ+EXECUTE)
            (IDENTIFIER=*,ACCESS=NONE)

  Total of 1 file.
<ENDCODE_EXAMPLE>

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

<HEAD1>(Maintaining Package Security\head_config_secure)

<P> As noted above, WASD version 8.1 and later is much more conservative in
what it makes generally available from the package tree, and a site
administrator now has to take extraordinary measures to open up certain
sections, making it a much more difficult and deliberate action.  The package
installation, update and security procedures and their associated utilities
should always be used to ensure that the installed package continues to conform
to it's security baseline.

<P> Package security may be <QUOTE>(refreshed) or reapplied at any time, and
this should be done periodically to ensure that an installed package has not
inadvertantly been opened to access where it shouldn't have.  Of course this
is not a guarantee that any given site is secure.  Site security is a function
of many factors; package vulnerabilities, site configuration, deployed scripts,
cracker determination and expertise, etc., etc.  What refreshing the security
baseline does is provide a known secure (and WASD-community scrutinized)
starting point.  It should be used as part of a well considered site security
maintenance program.

<HEAD>(SECURE.COM\head_config_install_secure)

<P> The following DCL procedure resets the package security baseline.

<CODE_EXAMPLE>
  $ @HT_ROOT:[INSTALL]SECURE.COM
<ENDCODE_EXAMPLE>

<P> It guides the administrator through a number of stages

<LIST>(UNNUMBERED)
<LE> introductory notes
<LE> server account
<LE> scripting account
<LE> package tree security settings
<ENDLIST>

<P> of which each one may be declined.  After all of these steps it searches
for and executes if found the DCL procedure HT_ROOT:[INSTALL]SECURE.COM. 
The intent of this file is to allow a site to automatically update any
site-specific security settings (and of course modify any set by the main
procedure).

<HEAD>(SECHAN Utility\head_config_sechan)

<P> The SECHAN utility (pronounced <QUOTE>(session)) is used by
SECURE.COM and its associated procedures to make file system security settings. 
It is also available for direct use by the site administrator
(<REFERENCE>(head_sechan)).

<P> One of the more useful functions of SECHAN is applied using the /IGNORE
qualifier.

<LIST>(UNNUMBERED)

<LE><EMPHASIS>(/IGNORE - \BOLD)
It adds an ACE containing the rights identifier WASD_IGNORE_THIS to the
target file(s) which results in security settings not being applied in the
future.  When applying settings the SECHAN utility first checks whether a file
has this ACE and if so ignores the file.  This is an effective method for
isolating site-specific settings from changes by this utility.

<CODE_EXAMPLE>
  $ SECHAN /IGNORE HT_ROOT:[CGI-BIN]MY_SCRIPT.COM
  $ SECHAN /IGNORE HT_ROOT:[LOCAL]*.DAT
  $ SECHAN /IGNORE WEB:[DATA...]*.*
  $ SECHAN /IGNORE WEB:[000000]DATA.DIR
<ENDCODE_EXAMPLE>

<P> This ACE can be removed from a file (leaving other entries of any ACL
intact) using the /NOIGNORE qualifier.  This returns the file(s) subject again
to the SECHAN utility.

<CODE_EXAMPLE>
  $ SECHAN /NOIGNORE HT_ROOT:[CGI-BIN]MY_SCRIPT.COM
  $ SECHAN /NOIGNORE HT_ROOT:[LOCAL]*.DAT
<ENDCODE_EXAMPLE>

<LE><EMPHASIS>(/ALL - \BOLD)
This overrides the default behaviour of ignoring files that have been tagged
using the /IGNORE qualifier.  It causes the setting to be applied to ALL files.

<ENDLIST>

<P> Other functionality may prove useful when applied to local parts of the
package or web structure.

<LIST>(UNNUMBERED)

<LE><EMPHASIS>(/PACKAGE - \BOLD)
Used alone this qualifier results in the entire HT_ROOT:[000000...] tree being
traversed and the default package security settings applied to all package
files.  Top-level directories that the utility does not recognise as belonging
to the package are ignored.

<CODE_EXAMPLE>
  $ SECHAN /PACKAGE
  $ SECHAN /PACKAGE /ALL
<ENDCODE_EXAMPLE>

<LE><EMPHASIS>(/ASIF=<LITERAL>(<name>) - \BOLD)
Set the supplied file specification as if it was the specified, top-level WASD
directory.  This allows a site-specific directory to have the same security
settings applied as the specified WASD package directory.

<CODE_EXAMPLE>
  $ SECHAN /ASIF=LOCAL WEB:[DATA...]*.*
  $ SECHAN /ASIF=LOCAL WEB:[000000]DATA.DIR
  $ SECHAN /ASIF=CGI-BIN WEB:[SCRIPTS]*.*
  $ SECHAN /ASIF=CGI-BIN WEB:[000000]SCRIPTS.DIR
  $ SECHAN /ASIF=DOC WEB:[HTML...]*.*
  $ SECHAN /ASIF=DOC WEB:[000000]HTML.DIR
<ENDCODE_EXAMPLE>

<LE><EMPHASIS>(/NOSCRIPT - \BOLD)
Modifies the default behaviour of the /PACKAGE qualifier.  This changes the
default rights identifiers applied to ACEs on files in the [CGI-BIN] and
[AXP-BIN]/[VAX-BIN] directories to disallow scripting until manually changed by
site administration.

<CODE_EXAMPLE>
  $ SECHAN /PACKAGE /NOSCRIPT
<ENDCODE_EXAMPLE>

<ENDLIST>

<P> This section provides only a basic description.  More detail may be found
in the prologue to the source code.

<HEAD1>(Independent Package and Local Resources\head_securing_separate)

<P> Not only does it make it easier to manage site content but is also good
security practice to keep server package and site content completely separate
(<REFERENCE>(head_organ_site)).

<P> This can also be applied to scripts, both source and build areas.  Keep
your business logic out of the package source tree and potentially prying eyes. 
The script executables themselves <EMPHASIS>(can) be placed into the package
scripting directories but should be built independently from these and copied
using locally maintained DCL procedures from build into scripting areas (the
HT_ROOT:[INSTALL]SECURE.COM procedures described above may be useful here).

<HEAD1>(Configuration\config_securing_config)

<P> Various configuration and mapping directives can be used to make the site
environment more or less liberal in the information it implicitly can provide.

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

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

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

<P> The mapping rule <QUOTE>(SET DIR=<EMPHASIS>(keyword)) can be used to
change this on a per-path basis (<REFERENCE>(head_set_rules)). 

<P> <EMPHASIS>(Conservative recommendation: \BOLD) Set <QUOTE>([DirAccess]
selective) allowing listing for directories containing a file named
<QUOTE>(.WWW_BROWSABLE), disable [DirMetaInfo] and [DirWildcard].

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

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

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

<P> The mapping rule <QUOTE>(SET REPORT=<EMPHASIS>(keyword)) can be used to
change some of these on a per-path basis (<REFERENCE>(head_set_rules)). 

<P> <EMPHASIS>(Conservative recommendation: \BOLD) Provide minimal error
information by enabling [ReportBasicOnly] and disabling [ReportMetaInfo]. 
Enable [ServerSignature] to provide a slightly more friendly report (server
software can easily be obtained from the response header anyway).

<HEAD2>(Scripting\config_secure_scripting)

<P> If a static site is all that's required this source of compromise can
simply be avoided.

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

<P> <EMPHASIS>(Conservative recommendation: \BOLD) Only deploy scripts your
site will actually be using.  Remove all the files associated with any other
scripts.  Do not allow obsolete script environments to remain active.  Be
proactive.

<P> Also see <REFERENCE>(config_securing_scripting).

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

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

<P> The mapping rule <QUOTE>(SET SSI=<EMPHASIS>(keyword)) can be used to
change some of this on a per-path basis (<REFERENCE>(head_set_rules)). 

<P> <EMPHASIS>(Conservative recommendation: \BOLD) Disable [SsiExec].

<HEAD1>(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 guaranteed and care should be exercised in their
deployment (ask me!)

<P> It is strongly recommended to execute scripts in an account distinct from
that executing the server. This should also mean that the accounts are not
members of the same group nor should it be a member of any other group. This
minimises the risk of both unintentional and malicious interference with server
operation through either Inter-Process Communication (IPC) or scripts
manipulating files used by the server. The PERSONA facility can be used to
further differentiate script activities.  See <QUOTE>(Scripting Overview) for
further detail.

<P> The default WASD installation creates two such accounts, with distinct
UICs, usernames and home directory space.  Nothing should be assumed or read
into the scripting account username - it's just a username.

<P>
<CENTER_LINE>(<EMPHASIS>(Default Accounts\BOLD))
<TABLE>
<TABLE_SETUP>(2\15)
<TABLE_HEADS>(Username\Description)
<TABLE_ROW>(HTTP$SERVER\Server Account)
<TABLE_ROW>(HTTP$NOBODY\Scripting Account)
<ENDTABLE>

<P> During startup the server checks for the existence of the default scripting
account and automatically configures itself to use this for scripting.  If it
is not present it falls-back to using the server account.  Other account names
can be used if the startup procedures are modified accordingly.  The default
scripting username may be overridden using the /SCRIPT=AS=<LITERAL>(<username>)
qualifier (also see the <QUOTE>(Scripting Overview)).

<HEAD1>(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.

<HEAD1>(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> Version 8.1 and later is much more conservative in what it makes available
of the package tree via the server.  The package installation, update and
security procedures and their associated utilities should always be used to
ensure that the installed package continues to conform to it's security
baseline.  See <REFERENCE>(head_config_secure).

<P> Furthermore, with 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 Server Administration page 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>

<NOTE>(Be careful!)
There are often multiple paths to a single resource.  For instance, it is of
little significance blocking access to say /ht_root/doc/ if it's also possible
to access it via /doc/.
<ENDNOTE>

<P> The following example shows how this might occur.

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

<P> Authorization rules can be used to effectively block access to any VMS file
specification (it cannot be done during mapping because the translation from
path to file system is not performed until mapping is complete).

<CODE_EXAMPLE>
  # HTTPD$AUTH
  if (path-translated:HT_ROOT:[DOC]*) * none
<ENDCODE_EXAMPLE>

<P> or to selectively allow access

<CODE_EXAMPLE>
  # HTTPD$AUTH
  [[WASD_VMS_RW=id]]
  if (path-translated:HT_ROOT:[DOC]*) * read
<ENDCODE_EXAMPLE>

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

<HEAD1>(Site Attacks\head_config_attacks)

<P> This is not a treatise on Web security and the author is not a security
specialist.  This is some general advice based on observation.  There is little
one can do at the server itself to reduce a concerted attack against a site. 
Common objectives of such attacks include the following (not an exhaustive
list).

<HEAD>(Platform Vulnerabilities\head_config_attacks_platform)

<P> Where a general attack is launched directed against a specific platform
(a combination of operating system and Web server software).  Often these can
be due to wide-spread infection of systems, meaning many attacks are being
launched from a large number of systems (often without the system owners'
knowlege or cooperation).

<P> WASD, and OpenVMS in particular, are generally immune to such attacks
because  they are not Microsoft or Unix based.  The impact of the attack
becomes one of the nuisance-value traffic as the site is probed by the
(sometimes very large number of) source systems.

<HEAD>(Site Vulnerabilities\head_config_attacks_site)

<P> Where a specific attack is made against a site in an attempt to exploit a
known vulnerability associated with that platform or environment.

<P> These are perhaps the most worrying, although the
<EMPHASIS>(security-by-obscurity) element works in favour of WASD and OpenVMS
in this case.  Neither are as common as other platforms and therefore do not
receive as much attention.

<HEAD>(Denial of Service\head_config_attacks_dos)

<P> (DOS) Usually comprise flooding a site with requests in an effort to
consume all available network or server resources making it unavailable for
legitimate use.

<P> These can be insidious, flooding network equipment as well as systems. 
Attempts at control are best undertaken at the periphery of the network
(routers) although concerted attacks can succeed against the best prepared
network.

<HEAD>(Password Cracking\head_config_attacks_crack)

<P> Where a systematic attempt to break into one or more accounts is
undertaken.  These are often repeated, dictionary-based password-guessing
attacks.

<P> WASD's authentication functionality notes successive password validation
failures and after a reasonable number disables all access via the username for
a constantly extended period.  Passwords stop being checked and so a
dictionary-based attack cannot succeed.  Password validation failures can be
recorded via OPCOM.

<HEAD>(Authorization Holes\head_config_attacks_auth)

<P> Knowing of or searching for resources that should be controlled by
authorization but are not.

<P> WASD's /AUTHORIZATION=ALL functionality may assist here
(<REFERENCE>(config_securing_auth)).

<HEAD>(Strategies\head_config_attacks_strategies)

<P> There are a few strategies for reducing the load on a server
experiencing a generalized attack or probing.  These can also be used to
<QUOTE>(discourage) the source from considering the site an easy target. 
Unfortunately most require request acceptance and at least some processing
before taking action.  The general idea is to identify either the source site
or some characteristic of the request that indicates it could not possibly be
legitimate.  Most platform-specific attacks have such a signature.  For
instance attacks against Microsoft platforms often involve probes for backdoors
into non-server executables.  These can be identified by the path containing
strings such as <QUOTE>(/winnt/), <QUOTE>(/system32/), <QUOTE>(/cmd.exe) or
variations on them.  This style will be used in examples below.

<LIST>(UNNUMBERED)

<LE> If the source IP address is known then the [Reject] (and/or [Accept])
configuration directives can be used to reject the request connection very
early in the processing.  The source agent receives a message about access
being rejected.

<CODE_EXAMPLE>
  [Reject]
  131.185.250.*
  the.host.name
<ENDCODE_EXAMPLE>

<P>

<LE> Mapping rules in combination with conditionals may be used to redirect the
request.  This redirection could be to another, non-existent site, in the hope
that the source agent will use the supplied URL and thus divert some activity
away from the local site.

<CODE_EXAMPLE>
  if (remote-host:the.host.name)
     redirect * http://the.host.name/*
  endif

  redirect **/winnt/** http://does.not.exist/
<ENDCODE_EXAMPLE>

<P>

<LE> Mapping rule redirection can also be used to just <QUOTE>(drop) the
connection without any further interaction or processing.  The source agent
receives no response, just a broken connection.

<CODE_EXAMPLE>
  if (remote-addr:131.185.250.*)
     pass * "000 just drop it!"
  endif

  pass **/system32/** "000 just drop it!"
<ENDCODE_EXAMPLE>

<P>

<LE> The <EMPHASIS>(hiss) facility (<REFERENCE>(head_hiss)) returns a stream of
random alpha-numeric characters (a sort of <EMPHASIS>(white-noise)).  No
response header is provided.  Such a response might cause the source agent at
best some distress (perhaps disabling it) or at least disuade it from
continuing with more probes (as the target is obviously not a Web server ;^)

<CODE_EXAMPLE>
  if (remote-addr:131.185.250.*) map * /hiss/*
  script /hiss/* /hiss/*

  map **/cmd.exe** /hiss/*/cmd.exe*
  script /hiss/* /hiss/*
<ENDCODE_EXAMPLE>

<ENDLIST>

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

<CHAPTER>(Server Configuration Directives\chapter_config_directives)

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

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

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

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

<P> By default, the system-table logical name HTTPD$CONFIG locates a common
configuration file, unless a per-server file is specified using a job-table
logical name.  Simple editing of the configuration file changes the rules. 
Alternatively the Server Administration page configuration interface may be
used.

<P> The [IncludeFile] is a directive common to all WASD configuration, allowing
a separate file to be included as a part of the current configuration.  See
<REFERENCE>(head_config_directives_include).

<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>([AuthCacheEntriesMax]\BOLD)\maximum concurrent
authentication cache entries)
<TABLE_ROW>(<EMPHASIS>([AuthCacheEntrySize]\BOLD)\maximum authentication cache
entry size in bytes)
<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)
<TABLE_ROW>(<EMPHASIS>([AuthSysUafAcceptExpPwd]\BOLD)\accept expired SYSUAF
passwords)
<TABLE_ROW>(<EMPHASIS>([AuthSysUafPwdExpURL]\BOLD)\redirection URL is SYSUAF
password is expired)
<TABLE_ROW>(<EMPHASIS>([AuthSysUafUseAcme]\BOLD)\use the ACME service for all
VMS SYSUAF based authentication)
<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>(Content-Type\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<COMMENT>(HTML=<TR></TR>)
<TABLE_ROW>(<EMPHASIS>([AddType]\BOLD)\add a content-type)
<TABLE_ROW>(<EMPHASIS>([AddMimeTypesFile]\BOLD)\add the contents of a standard
MIME.TYPES file)
<TABLE_ROW>(<EMPHASIS>([CharsetConvert]\BOLD)\conversion of one character set
to another)
<TABLE_ROW>(<EMPHASIS>([CharsetDefault]\BOLD)\default character set for text
responses)
<TABLE_ROW>(<EMPHASIS>([StreamLF]\BOLD)\enable and set maximum size of
automatic Stream-LF conversion)
<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>([AddDefaultIcon]\BOLD)\path to default 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>([CacheFrequentIntervals]\BOLD)\identify active files)
<TABLE_ROW>(<EMPHASIS>([CacheFrequentPeriod]\BOLD)\identify active file)
<TABLE_ROW>(<EMPHASIS>([CacheGuardPeriod]\BOLD)\prevent early reloads)
<TABLE_ROW>(<EMPHASIS>([CacheTotalKBytesMax]\BOLD)\maximum memory to be
consumed by cache)
<TABLE_ROW>(<EMPHASIS>([CacheValidatePeriod]\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>([LogExtend]\BOLD)\default allocation/extend in blocks)
<TABLE_ROW>(<EMPHASIS>([LogFile]\BOLD)\provides part or all of log file name)
<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>([LogPerInstance]\BOLD)\create a separate log for each
instance process)
<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 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, SSL
private key password requests))
<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>([Busy]\BOLD)\number of concurrent connections allowed)
<TABLE_ROW>(<EMPHASIS>([DNSLookupClient]\BOLD)\enable client host name lookup)
<TABLE_ROW>(<EMPHASIS>([DNSLookupLifeTime]\BOLD)\host name lookup cache entry
lifetime)
<TABLE_ROW>(<EMPHASIS>([DNSLookupRetry]\BOLD)\number two second attempts to
resolve client host name)
<TABLE_ROW>(<EMPHASIS>([InstanceMax]\BOLD)\number of per-node server processes
to maintain)
<TABLE_ROW>(<EMPHASIS>([Monitor]\BOLD)\enable HTTPDMON data exchange)
<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>([RegEx]\BOLD)\enable regular expression matching)
<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>([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>([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>([ProxyCacheNoReloadSeconds]\BOLD)\prevent pragma reloads
for this period)
<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>([ProxyCacheRoutineHourOfDay]\BOLD)\hour of day routine
cache purge occurs)
<TABLE_ROW>(<EMPHASIS>([ProxyForwarded]\BOLD)\add <QUOTE>(Forwarded:) to
requests)
<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)
<TABLE_ROW>(<EMPHASIS>([ProxyXForwardedFor]\BOLD)\add <QUOTE>(X-Forwarded-For:)
to requests)
<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)\period a connection can wait
before sending request)
<TABLE_ROW>(<EMPHASIS>([TimeoutKeepAlive]\BOLD)\period a connection is kept
active after request conclusion)
<TABLE_ROW>(<EMPHASIS>([TimeoutOutput]\BOLD)\period a response can continue to
output)
<TABLE_ROW>(<EMPHASIS>([TimeoutNoProgress]\BOLD)\period 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>([DclBitBucketTimeout]\BOLD)\period a script continues
after a client prematurely disconnects)
<TABLE_ROW>(<EMPHASIS>([DclCgiPlusLifeTime]\BOLD)\period 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)\period of non-use before a
CGI/CLI subprocess is deleted)
<TABLE_ROW>(<EMPHASIS>([DECnetReuseLifeTime]\BOLD)\period 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)
<TABLE_ROW>(<EMPHASIS>([SSIsizeMax]\BOLD)\maximum source file size)
<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 literal 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>

<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 page
(<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.

<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>([AddDefaultIcon] <EMPHASIS>(icon-URL) <EMPHASIS>(ALT-text)\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    _____
  [AddDefaultIcon]  /icon/-/file.gif     [FIL]
  [AddDirIcon]      /icon/-/dir.gif      [DIR]
  [AddParentIcon]   /icon/-/back.gif     <LITERAL>([<--])
  [AddUnknownIcon]  /icon/-/unknown.gif  [???] 
<ENDCODE_EXAMPLE>

<LE> <EMPHASIS>([AddMimeTypesFile] <EMPHASIS>(file specification)\BOLD)
<EMPHASIS>((no default)) 

<P> Add the content-types of a (de facto) standard MIME.TYPES file to the
already configured [AddType] content-types.  This binds a file suffix
(extension, type) to a MIME content-type.  Any specification in this file will
supercede any previously defined via [AddType].  A MIME.TYPES file looks
something like

<CODE_EXAMPLE>
  # MIME type			Extension
  application/msword            doc
  application/octet-stream      bin dms lha lzh exe class
  application/oda               oda
  application/pdf               pdf
  application/postscript        ai eps ps
  application/rtf               rtf
<ENDCODE_EXAMPLE>

<P> The WASD server uses a number of extensions to provide additional
information.  See <REFERENCE>(head_config_content_type).

<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> To provide additional information for correct handling of FTP transfers the
content-type may have an FTP transfer mode indicated.  This is provided by
appending the mode directly after the content type (allow no white-space).  One
of three characters is used.  An <QUOTE>(A) indicates that this file type
should be FTP transfered in ASCII mode.  An <QUOTE>(I) or a <QUOTE>(B)
indicates that this file type should be FTP transfered in Image (binary) mode. 
The following example provides the syntax.

<CODE_EXAMPLE>
  [AddType]
  .ps    application/postscript(ftp:A)   Postscript document
<ENDCODE_EXAMPLE>

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

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

<LE> <EMPHASIS>([AuthCacheEntrySize] <EMPHASIS>(integer)\BOLD) 
<EMPHASIS>((default: 768)) 

<P> Maximum size of an authentication cache entry.  The only reason where this
may need to be increased is where a site is using the /PROFILE functionality
and one or more accounts have a particularly large number of rights
identifiers.

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

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

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

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

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

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

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

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

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

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

<P> If a SYSUAF authenticated password has expired (password lifetime has
been reached) accept it anyway (in much the same way network logins are
accepted in similar circumstances).  This is very different to
<EMPHASIS>(account expiry), after which authentication is always rejected.

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

<P> If a SYSUAF authenticated password is/has expired the request is redirected
to this URL to change the password.
See <REFERENCE>(head_auth_user_password_change)

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

<P> On applicable platforms (Alpha (and IA64?), OpenVMS 7.3 and later) use the
ACME service to perform SYSUAF authentication and SYSUAF password change. The
immediate advantage of using ACME is the processing of the (rather complex)
authentication requirements by a vendor-supplied implementation.  It also
allows SYSUAF password change to be made subject to the full site policy
(password history, dictionary checking, etc.) which WASD does not implement.

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

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

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

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

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

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

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

<P> File cache control.

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

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

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

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

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

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

<LE> <EMPHASIS>([CacheFrequentPeriod] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 00:00:00))

<P> If a file has been hit at least [CacheFrequentIntervals] times in total and the
last was within the period here specified it will not be a candidate for reuse.
See <REFERENCE>(chapter_cache).

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

<P> During this period subsequent <EMPHASIS>(reloads) (no-cache) requests will
not result in the entry being revalidated or reloaded.  This can guard period
can help prevent unnecessary file system activity.

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

<P> <EMPHASIS>(Obsolete for WASD V8.0 and following.)

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

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

<LE> <EMPHASIS>([CacheValidatePeriod] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 00:00:00))

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

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

<P> Document and CGI script output can be dynamically converted from one
character set to another using the standard VMS NCS conversion library.  This
directive provides the server with character set aliases (those that are for
all requirements the same) and which NCS conversion function may be used to
convert one character set into another.  The general format is

<CODE_EXAMPLE>
  document-charset  accept-charset[,accept-charset..]  [NCS-function-name]
<ENDCODE_EXAMPLE>

<P> When this directive is configured the server compares each text response's
character set (if any) to each of the directive's <EMPHASIS>(document charset)
string.  If it matches it then compares each of the <EMPHASIS>(accepted
charset) (if multiple) to the request <QUOTE>(Accept-Charset:) list of accepted
characters sets.  If the same is is either accepted as-is or if a conversion
function specified converted by NCS as the document is transfered.

<CODE_EXAMPLE>
  windows-1251 windows-1251,cp-1251
  windows-1251 koi8-r koi8r_to_windows1251_to_koi8r
  koi8-r koi8-r,koi8
  koi8-r windows-1251,cp-1251 koi8r_to_windows1251
<ENDCODE_EXAMPLE>

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

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

<LE> <EMPHASIS>([DclBitBucketTimeout] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 0))

<P> Period a script is allowed to continue processing before being terminated
after a client prematurely disconnects.  An approptiate setting allows most
scripts to conclude elegantly and be available for further use.  This improves
scripting efficiency significantly.  Setting this period to zero terminates
scripts (and their associated processes) immediately a client is detected as
having disconnected.

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

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

<LE> <EMPHASIS>([DclCgiPlusLifeTime] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 0))

<P> 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
period  after it last processed a request.  This helps prevent sporadically
used scripts from clogging up a system.

<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 (<REFERENCE>(head_httpd_command_line),
<REFERENCE>(head_user_scripts) and in particular <QUOTE>(Scripting Overview, 
Introduction).

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

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

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

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

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

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

<LE> <EMPHASIS>([DclZombieLifeTime] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 00:00:00))           

<P> If this value is zero the use of persistant DCL subprocesses is disabled. 
If non-zero the <EMPHASIS>(zombie)  subprocess is terminated the specified
period after it last processed a request.  This helps prevent zombie processes
from clogging up a system.  See <QUOTE>(Scripting Environment) document.

<LE> <EMPHASIS>([DECnetReuseLifeTime] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 00:00:00))              

<P> Period a DECnet scripting connection is maintained with the network task. 
Zero disables connection reuse.

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

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

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

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

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

<LIST>(SIMPLE)
<LE><EMPHASIS>(C\BOLD) - creation date
<LE><EMPHASIS>(D\BOLD) - description (generally best specified last)
<LIST>(SIMPLE)
<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>(SIMPLE)
<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>(SIMPLE)
<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>

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

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

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

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

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

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

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

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

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

<P> Examples: 

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

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

<LE> <EMPHASIS>([DNSLookupClient] <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 literal internet address.  If not enabled 
any [Accept], [Reject] or conditional directive, etc., must be expressed as a
literal address.

<LE> <EMPHASIS>([DNSLookupLifetime] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>(default 00:10:00) 

<P> The period for which a host name/address is cached (applies to both client
lookup and proxy host lookup).

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

<P> The number of attempts, at two second intervals, made to resolve a host
name/address (applies to both client lookup and proxy host lookup).

<LE> <EMPHASIS>([ErrorReportPath] <EMPHASIS>(string [status...])\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.  Optional,
space-separated HTTP status codes restrict the path to those codes, with the
remainder handled by server-internal reporting.

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

<LE> <EMPHASIS>([InstanceMax]
<EMPHASIS>(integer)<VBAR><EMPHASIS>(CPU\SMALLCAPS)\BOLD)
<EMPHASIS>((default: 1)) 

<P> Number of per-node server processes to create and maintain.
If set to <QUOTE>(CPU) once instance per CPU is created.

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

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

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

<P> Number of blocks allocated when when a log file is opened or extended.  If
set to zero it uses the process default (SET RMS_DEFAULT /EXTEND_QUANTITY).

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

<P> Provides some or all of the access log file name.
See <REFERENCE>(head_log_period).

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

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

<P> Number of global buffers to use when multiple instances are configured. 
This directive improves performance (by delaying write-to-disk) of
multi-instance configurations by using RMS global buffering for shared write
access to log files.  As each log file has a multiblock count of 127 this is
probably best specified as 1 or some other small number.  It consumes global
sections and global pages from system-wide resources.

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

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

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

<P> When multiple instances are configured (<REFERENCE>(head_config_instances)) 
create a separate log for each.  This has significant performance advantages. 
See <REFERENCE>(head_log_per_instance).

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

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

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

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

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

<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 administration directives originating from the Server Administration
Menu, for example path map reload, server restart, etc.

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

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

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

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

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

<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 (<REFERENCE>(head_httpd_control)) this
parameter is overridden by anything supplied via the [Service] directive.

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

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

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

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

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

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

<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 files per directory issue.

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

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

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

<P> Prevents pragma reloads actually retrieving the file from the source host
again  until the period expires.  This is designed to limit concurrent or
repeated reloads of files into the cache unecessarily.  Thirty seconds is
probably an adequate period balancing effect against a user legitimately
needing to recache the document.

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

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

<LE> <EMPHASIS>([ProxyForwarded]
<EMPHASIS>(BY<VBAR>DISABLED<VBAR>FOR<VBAR>ADDRESS\SMALLCAPS)\BOLD)
<EMPHASIS>((default: DISABLED)) 

<P> BY enables 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://server.name.domain
(HTTPd-WASD/n.n.n OpenVMS/AXP Digital-TCPIP SSL)).  If the FOR variant is used
the field included the host name (or ADDRESS) the request is being forwarded on
behalf of, as in <QUOTE>(Forwarded: by http://server.name.domain
(HTTPd-WASD/n.n.n OpenVMS/AXP Digital-TCPIP SSL) for host.name.domain).

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

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

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

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

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

<P> Enables the addition of a proxy request header line providing the host name
on behalf of which the request is being proxied.  The added header line would
look like <QUOTE>(X-Forwarded-For: host.name.domain).  THE ADDRESS variant
provides the IP address, and the UNKNOWN variant substitutes
<QUOTE>(unknown) for the host.  This field is degined to be compatible with
the <EMPHASIS>(Squid) de facto standard field of the same name.  Any request
with an existing <QUOTE>(X-Forwarded-For:) field has the local information
appended to the existing as a comm-separated list.  The first host in the field
should be the original requesting client.

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

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

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

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

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

<P> Enable regular expression matching.  With the possibility of the reserved
character <QUOTE>(^) being used in existing mapping rules regular expression
string matching (<REFERENCE>(chapter_string_matching)) is only available after
enabling this directive.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<LE> <EMPHASIS>([SSIsizeMax] <EMPHASIS>(integer)\BOLD)
<EMPHASIS>((default: 0 (128kB))) 

<P> SSI source files a completely read into memory before processing.  This
allows the maximum size to be expanded beyond the default.

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

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

<LE> <EMPHASIS>([TimeoutInput] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 00:01:00)) 

<P> Period allowing a connection request to be in progress without 
submitting a complete request header before terminating it. 

<LE> <EMPHASIS>([TimeoutKeepAlive] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 00:00:05)) 

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

<LE> <EMPHASIS>([TimeoutNoProgress] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 00:02:00)) 

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

<LE> <EMPHASIS>([TimeoutOutput] <EMPHASIS>(hh:mm:ss)\BOLD)
<EMPHASIS>((default: 00:10:00)) 

<P> Period allowing a request to be output before terminating it. 
This directive sets an absolute maximum time a request can continue to receive
output.

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

<P> Enables session (user) tracking.

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

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

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

<CODE_EXAMPLE>
  [Welcome]
  index.html
  index.htm
  home.html
  home.htm
<ENDCODE_EXAMPLE>

<P> Dynamic home pages (script or interpreter engine driven, e.g. Perl, PHP)
may be deployed using a combination of the [Welcome] and [DclScriptRunTime]
directives.

<CODE_EXAMPLE>
  [Welcome]
  index.html
  index.htm
  index.php
  index.pl

  [DclScriptRunTime]
  .PHP $CGI-BIN:[000000]PHPWASD.EXE
  .PL $CGI-BIN:[000000]PERLRTE
<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> There is no design limit to the number of services that WASD can support. 
It can listen on any number of IP ports and for any number of virtual services
for any given port.

<HEAD>(Specific Services\head_service_specific)

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

<LIST>(UNNUMBERED)

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

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

<LE><EMPHASIS>(port - \BOLD) IP port the service is offered on.  If omitted 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 (<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.

<HEAD>(Administration Services\head_service_admin)

<P> When multiple instances are configured Server Administration page access,
in common with all request processing, is automatically shared between those
instances.  There are occasions when consistent access to a single instance is
desirable.  The [ServiceAdmin] directive indicates that the service port
number should be used as a <UNDERLINE>(base) port and all instances create
their own service with unique port for access to that instance alone. The first
instance to create an <EMPHASIS>(administration service) uses the specified
port, or the next successive if it's already in use, the next instance will use
the next available port number, and so on.  A high port number should be
specified.  The Server Administration page lists these services for all server
instances in the cluster.  This port configuration is not intended for general 
request activity, although with appropriate mapping and other configuration
there is nothing specifically precluding it's use (remembering that the actual
port in use by any particular instance may vary across restarts).  In all other
respects the services can (and should) be  mapped, authorized and otherwise
configured as any other. See <REFERENCE>(head_service_directives_example).

<HEAD1>(IPv4 and IPv6\head_service_ipv4_ipv6)

<P> Both IP version 4 and 6 are concurrently supported by WASD.  All networking
functionality, service creation, SSL, proxy HTTP, proxy FTP and RFC1413
authorization is IPv6 enabled.  If system TCP/IP services do not support IPv6
the expected error would be

<CODE_EXAMPLE>
  %SYSTEM-F-PROTOCOL, network protocol error
<ENDCODE_EXAMPLE>

<CP> during any attempted IPv6 service creation.  Of course IPv4 service
creation would continue as usual.

<P> Server configuration handles the standard dotted-decimal addresses of IPv4,
as well as <quote>(normal) and <quote>(compressed) forms of standard IPv6
literal addresses, and a (somewhat) standard variation of these that
substitutes hyphens for the colons in these addresses to allow the
colon-delimited port component of a <QUOTE>(URL) to be resolved.

<P>
<CENTER_LINE>(<EMPHASIS>(IPv6 Literal Addresses\BOLD))
<TABLE>
<TABLE_SETUP>(2\25)
<TABLE_HEADS>(Normal\Compressed)
<TABLE_ROW>(1070:0:0:0:0:800:200C:417B\1070::800:200C:417B)
<TABLE_ROW>(0:0:0:0:0:0:13.1.68.3\::13.1.68.3)
<TABLE_ROW>( 0:0:0:0:0:FFFF:129.144.52.38\::FFFF:129.144.52.38)
<TABLE_HEADS>(hyphen-variants\)
<TABLE_ROW>(1070-0-0-0-0-800-200C-417B\1070--800-200C-417B)
<TABLE_ROW>(0-0-0-0-0-0-13.1.68.3\--13.1.68.3)
<TABLE_ROW>(0-0-0-0-0-FFFF-129.144.52.38\--FFFF-129.144.52.38)
<ENDTABLE>

<P> In common with all virtual services, if a connection can be established
with the system and service port the HTTPd can respond to that request.  If a
service needs to be bound to a specific IP address then that can be specified
using the [ServiceBind] directive using any of the literal address formats
described above.

<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>([ServiceAdmin]\BOLD)\an <EMPHASIS>(instance) Server
Administration page service)
<TABLE_ROW>(<EMPHASIS>([ServiceBind]\BOLD)\if different to host's)
<TABLE_ROW>(<EMPHASIS>([ServiceBodyTag]\BOLD)\<LITERAL>(<BODY>) tag for server
reports., etc)
<TABLE_ROW>(<EMPHASIS>([ServiceClientSSLcipherList]\BOLD)\
proxy SSL connect ciphers)
<TABLE_ROW>(<EMPHASIS>([ServiceClientSSLverifyCA]\BOLD)\
verify CA of proxied requests)
<TABLE_ROW>(<EMPHASIS>([ServiceClientSSLverifyCAfile]\BOLD)\
location of proxy CA file)
<TABLE_ROW>(<EMPHASIS>([ServiceClientSSLversion]\BOLD)\
proxy SSL version to use)
<TABLE_ROW>(<EMPHASIS>([ServiceErrorReportPath]\BOLD)\path to script, SSI or
<QUOTE>(flat) error document)
<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>([ServiceProxySSL]\BOLD)\proxy SSL enable)
<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>([ServiceSSLcipherList]\BOLD)\list of accepted SSL ciphers)
<TABLE_ROW>(<EMPHASIS>([ServiceSSLkey]\BOLD)\SSL service private key)
<TABLE_ROW>(<EMPHASIS>([ServiceSSLverifyPeer]\BOLD)\
access only using verified peer certificate)
<TABLE_ROW>(<EMPHASIS>([ServiceSSLverifyPeerCAfile]\BOLD)\location of CA file)
<TABLE_ROW>(<EMPHASIS>([ServiceSSLversion]\BOLD)\SSL version to use)
<ENDTABLE>

<HEAD1>(Directive Detail\head_service_directives_detail)

<P> Some of these directives control the behaviour of proxy services.  Refer to
<REFERENCE>(chapter_proxy_serving) for further detail.  Other directive are
Secure Sockets Layer (SSL) specific.  This is an optional package described in
<REFERENCE>(chapter_ssl).

<LIST>(NUMBERED)

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

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

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

<P> Marks the port as <EMPHASIS>(administration) service
(<REFERENCE>(head_service_admin)).

<LE> <EMPHASIS>([ServiceBind] <EMPHASIS>(literal 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.  The literal address may be in IPv4 dotted-decimal or IPv6
normal or compressed hexdecimal.

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

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

<P> Enables a proxy service to <EMPHASIS>(originate) HTTP-over-SSL requests. 
This is different to the CONNECT service enabled using [ServiceProxySSL].  It
allows requests to be gatewayed between standard HTTP and Secure Sockets Layer
(see <REFERENCE>(head_proxy_gatewaying)).

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

<P> A comma-separated list of SSL ciphers to be used by the gateway to connect
to SSL services.  The use of this parameter might allow the selection of
stronger ciphers to be forced to be used or the connection not allowed to
procede.

<NOTE>
These <EMPHASIS>(ServiceClientSSL..) directives are used to control
behaviour when outgoing SSL connections are established (as with HTTP-to-SSL
gatewaying).  This should not be confused with verification of client
certificates, which is better refered to as peer verification.  See
[ServiceSSLverifyPeer] and [ServiceSSLverifyPeerCAfile] directives.
<ENDNOTE>

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

<P> Unless this directive is enabled the Certificate Authority (CA)
used to issue the service's certificate is not verified.  Requires that a CA
file be provided.  See note in [ServiceClientSSLcipherList] above.

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

<P> Specifies the location of the collection of Certificate Authority (CA)
certificates used to verify the connected-to server's certificate (VMS file
specification).  See note in [ServiceClientSSLcipherList] above.

<LE> <EMPHASIS>([ServiceClientSSLversion] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: SSLV2/V3)) 

<P> The abbreviation for the SSL protocol version to be used to connect
to the SSL service.  See note in [ServiceClientSSLcipherList] above.

<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 (<REFERENCE>(head_error_reporting)). This
path can subsequently be remapped during request processing.

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

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

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

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

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

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

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

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

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

<P> Specifies the next proxy host if chained.

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

<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.  This proxies <QUOTE>(https:)
requests directly and is different to the HTTP-to-SSL proying described in
<REFERENCE>(head_proxy_connect_serving) and enabled using [ServiceProxyHttpSSL].

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

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

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

<P> A comma-separated list of SSL ciphers allowed to be used by clients to
connect to SSL services.  The use of this parameter might allow the selection
of stronger ciphers to be forced to be used or the connection not allowed to
procede.

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

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

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

<P> To access this service a client must provide a verified CA client
certificate (<REFERENCE>(head_ssl_x509_auth)).

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

<P> Specifies the location of the collection of Certificate Authority (CA)
certificates used to verify a peer certificate (VMS file specification,
<REFERENCE>(head_ssl_x509_auth)).

<LE> <EMPHASIS>([ServiceSSLversion] <EMPHASIS>(string)\BOLD)
<EMPHASIS>((default: SSLV2/V3)) 

<P> The abbreviation for the SSL protocol version allowed to be used to connect
to an SSL service.  Using the directive a service may select prefered (read
stronger) protocols.

<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 page may be used
(<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> The [IncludeFile] is a directive common to all WASD configuration, allowing
a separate file to be included as a part of the current configuration
(<REFERENCE>(head_config_directives_include)).

<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.domain.name:80]]

  [[http://alpha.domain.name:8080]]
  [ServiceProxy]  enabled
  [ServiceProxyAuth]  PROXY
  [ServiceProxyCache]  enabled
  [ServiceProxySSL]  enabled

  [[https://alpha.domain.name: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>

<LE> The following example show two services configured against specific IP
addresses.  The first is an IPv4 and the second a compressed IPv6.

<CODE_EXAMPLE>
  [[http://alpha4.domain.name:80]]
  [ServiceBind]  168.192.0.3

  [[https://alpha6.domain.name:80]]
  [ServiceBind]  fe80::200:f8ff:fe24:1a22
<ENDCODE_EXAMPLE>

<LE> An <EMPHASIS>(administration port) is a special configuration used to
support the Server Administration page (<REFERENCE>(chapter_server_admin)) when
multiple per-node instances are configured
(<REFERENCE>(head_config_instances)).  See description above.

<CODE_EXAMPLE>
  [[https://alpha.domain.name:44443]]
  [ServiceAdmin]  enabled
  [ServiceSSLcert] ht_root:[local]alpha.pem
  [ServiceSSLkey] ht_root:[local]alpha.pem
<ENDCODE_EXAMPLE>


<ENDLIST>

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

<CHAPTER>(Message Configuration\chapter_msg_config)

<P> Message configuration is provided for two purposes.

<LIST>(NUMBERED)

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

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

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

<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>
<CENTER_LINE>(
<EMPHASIS>(Care must be taken with the message file or the server
may refuse to start!\BOLD)
<LINE>Worst-case; the HTTPD$MSG.CONF message file may be copied from
[EXAMPLE].)
<ENDNOTE>

<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]   8.0
  [language]  1  es,es-ES,es-AR  hosts=*.es,*.ar
  [language]  2  de,de-*         hosts=*.de,*.at
  [language]  3  en

  [general]

  en 01 Sanity check failure.
  de 01 (the same message but in German, which I cannot speak :^)
  es 01 (the same message but in Spanish, which I also cannot speak :^)
  en 02 String overflow.
  de 02 (the same message but in German, which I cannot speak :^)
  es 01 (the same message but in Spanish, \
  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>(UNNUMBERED)

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

<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.)  Multiple, comma-separated
languages may be specified.  The first is the primary language of that list and
messages must be specified using that.  The subsequent languages are
equivalents that might be specified by the client.  A wildcard may be used to
match all possibilities (e.g. <QUOTE>(de,de-*), <QUOTE>(es,es-*)).  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.
A character set may be associated with a particular language by specifying a
<EMPHASIS>(charset=) following the language string (e.g. <QUOTE>(ru
charset=koi8-r)).  Setting the language's ordering number to zero disables the
language completely.  All messages associated with it will then be ignored.

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

<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>(<VBAR>).  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>(String Matching\chapter_string_matching)

<P> Matching of strings is a pervasive and important function within the
server.  Two types are supported; wildcard and regular expression.  Wildcard
matching is generally much less expensive (in CPU cycles and time) than regular
expression matching and so should always be used unless the match explicitly
requires otherwise. WASD attempts to improve the efficiency of both by
performing a preliminary pass to make simple matches and eliminate obvious
mismatches using a very low-cost comparison.   This either matches or doesn't,
or encounters a pattern matching meta-character which causes it to undertake
full pattern matching.

<P> To assist with the refinement of string matching patterns the
Server Administration facility (<REFERENCE>(chapter_server_admin)) has a report
item named <QUOTE>(Match).  This report allows the input of target and match
strings and allows direct access to the server's wildcard and regular
expression matching routines.  Successful matches show the matching elements
and a substitution field (<REFERENCE>(head_string_matching_subs)) allows
resultant strings to be assessed.

<P> To determine what string match processing is occuring during request
processing in the running server use the <EMPHASIS>(match) item available
from the Server Administration WATCH Report (<REFERENCE>(chapter_watch)).

<HEAD1>(Wildcard Patterns\head_string_matching_wildcard)

<P> Wildcard patterns are simple, low-cost mechanisms for matching a
string to a template.  They are designed to be used in path and authorization
mapping to compare a request path to the root (left-hand side) or a template
expression.

<P>
<CENTER_LINE>(<EMPHASIS>(Wildcard Operators\BOLD))
<TABLE>
<TABLE_SETUP>(2\20)
<TABLE_HEADS>(Expression\Purpose)
<TABLE_ROW>(*\Match zero or more characters (non-greedy))
<TABLE_ROW>(**\Match zero or more characters (greedy))
<TABLE_ROW>(%\Match any one character)
<ENDTABLE>
 
<P> Wildcard matching uses the '*' and '%' symbols to match any zero or more,
or any one character respectively.  The '*' wildcard can either be greedy or
non-greedy depending on the context (and for historical reasons).  It can also
be forced to be greedy by using two consecutive ('**').  By default it is not
greedy when matching request paths for mapping or authentication, and is greedy
at other times (matching strings within conditional testing, etc.)

<HEAD>(Greedy and Non-Greedy\head_string_matching_non_greedy)

<P> Non-greedy matching attempts to match an asterisk wildcard up until the
first character that is not the same as the character immediately following the
wildcard.  It matches a minimum number of characters before failing.
Greedy matching attempts to match all characters up until the first string
that does not match what follows the asterisk.

<P> To illustrate; using the following string

<CODE_EXAMPLE>
  non-greedy character matching compared to greedy character matching
<ENDCODE_EXAMPLE>

the following non-greedy pattern

<CODE_EXAMPLE>
  *non-greedy character*matching
<ENDCODE_EXAMPLE>

does not match but the following greedy pattern

<CODE_EXAMPLE>
  *non-greedy character**matching
<ENDCODE_EXAMPLE>

does match.  The non-greedy one failed as soon as it encountered the space
following the first <QUOTE>(matching) string, while the greedy pattern
continued to match eventually encountering a string matching the string
following the greedy wildcard.

<HEAD1>(Regular Expressions\head_string_matching_regex)

<P> Regular expression matching is case insensitive (in line with other WASD
behaviour) and uses the Posix EGREP pattern syntax and capabilities.  Regular
expression matching offers significant but relatively expensive functionality. 
One of those expenses is expression compilation.  WASD attempts to eliminate
this by pre-compiling expressions during server startup whenever feasable. 
Regular expression matching must be enabled using the [RegEx] HTTPD$CONFIG
directive and are then differentiated from wildcard patterns by using a leading
<QUOTE>(^) character.

<P> A detailed tutorial on regular expression capabilities and usage is well
beyond the scope of this document.  Many such hard-copy and on-line documents
are available. This summary is only to serve as a quick mnemonic.  WASD regular
expressions support the following set of operators.

<P>
<CENTER_LINE>(<EMPHASIS>(Operator Overview\BOLD))
<TABLE>
<TABLE_SETUP>(2\20)
<TABLE_HEADS>(Description\Usage)
<TABLE_ROW>(Match-self Operator\Ordinary characters.)
<TABLE_ROW>(Match-any-character Operator\.)
<TABLE_ROW>(Concatenation Operator\Juxtaposition.)
<TABLE_ROW>(Repetition Operators\*  +  ? {})
<TABLE_ROW>(Alternation Operator\<VBAR>)
<TABLE_ROW>(List Operators\[...]  [^...])
<TABLE_ROW>(Grouping Operators\(...))
<TABLE_ROW>(Back-reference Operator\<BACKSLASH>digit)
<TABLE_ROW>(Anchoring Operators\^  $)
<TABLE_ROW>(Backslash Operator\Escape meta-character; i.e.
<BACKSLASH> ^ . $ <VBAR> [ <OPAREN>)
<ENDTABLE>

<P> The following operators are used to match one, or in conjunction with the
repetition operators more, characters of the target string.  These single and
leading characters are reserved meta-characters and must be escaped using a
leading backslash (<QUOTE>(<BACKSLASH>)) if required as a literal character in
the matching pattern.

<P>
<CENTER_LINE>(<EMPHASIS>(Matching Operators\BOLD))
<TABLE>
<TABLE_SETUP>(2\20)
<TABLE_HEADS>(Expression\Purpose)
<TABLE_ROW>(^\Match the beginning of the line)
<TABLE_ROW>(.\Match any character)
<TABLE_ROW>($\Match the end of the line)
<TABLE_ROW>(<VBAR>\Alternation (or))
<TABLE_ROW>([abc]\Match only a, b or c)
<TABLE_ROW>([^abc]\Match anything except a, b and c)
<TABLE_ROW>([a-z0-9]\Match any character in the range a to z or 0 to 9)
<ENDTABLE>
 
<P> Repetition operators control the extent, or number, of whatever the
matching operators match. These are also reserved meta-characters and must be
escaped using a leading backslash if required as a literal character.

<P>
<CENTER_LINE>(<EMPHASIS>(Repetition Operators\BOLD))
<TABLE>
<TABLE_SETUP>(2\20)
<TABLE_HEADS>(Expression\Function)
<TABLE_ROW>(*\Match 0 or more times)
<TABLE_ROW>(+\Match 1 or more times)
<TABLE_ROW>(?\Match 1 or zero times)
<TABLE_ROW>({n}\Match exactly n times)
<TABLE_ROW>({n,}\Match at least n times)
<TABLE_ROW>({n,m}\Match at least n but not more than m times)
<ENDTABLE>
 
<HEAD1>(Examples\head_string_matching_examples)

<P> The following provides a series of examples as they might occur in use
for server configuration.

<LIST>(NUMBERED)

<LE> Equivalent functionality using wildcard and regular expression patterns. 
Note that <QUOTE>(Mozilla) must be at the start of the string, with the
regular expression using the start-of-string anchor resulting in two
consecutive <QUOTE>(^)s, one indicating to WASD a regular expression, the other
being part of the expression itself.

<CODE_EXAMPLE>
  if (user-agent:Mozilla*Gecko*)
  if (user-agent:^^Mozilla.*Gecko)
<ENDCODE_EXAMPLE>

<LE> This shows path matching using equivalent wildcard and regular expression
matching.  Note the requirement to use the regular expression
<EMPHASIS>(grouping) parentheses to provide the substitution elements,
something provided implicitly with wildcard matching.

<CODE_EXAMPLE>
  map /*/-/* /ht_root/runtime/*/*
  map ^/(.+)/-/(.+) /ht_root/runtime/*/*
<ENDCODE_EXAMPLE>

<LE> This rather contrived regular expression example has no equivalent
capability available with wildcard matching.  It forbids the use of any path
that contains any character other than alpha-numerics, the hyphen, underscore,
period and forward-slash.

<CODE_EXAMPLE>
  pass ^[^-_./a-z0-9]+ "403 Forbidden character in path!"
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD1>(Expression Substitution\head_string_matching_subs)

<P> Expression substitution is available during path mapping
(<REFERENCE>(chapter_mapping_rule)).  Both wildcard (implicitly) and regular
expressions (using <EMPHASIS>(grouping) operators) note the offsets of matched
portions of the strings.  These  are then used for wildcard and
<EMPHASIS>(specified) wildcard substitution where result strings provide for
this (e.g. mapping 'pass' and 'redirect' rules).  A maximum of nine such
wildcard substitutions are supported (one other, the zeroeth, is the full
match).

<HEAD>(Wildcard Substitution\head_string_matching_subs_wild)

<P> With wildcard matching each asterisk wildcard contained in the pattern
(<EMPHASIS>(template) string) has matching characters in the 
<EMPHASIS>(target) string noted and stored.  Note that for the percentage
(single character) wildcard no such storage is provided.  These characters are
available for substitution using corresponding wildcards present in the
<EMPHASIS>(result) string.  For instance, the target string

<CODE_EXAMPLE>
  this is an example target string
<ENDCODE_EXAMPLE>

<CP> would be matched by the pattern string

<CODE_EXAMPLE>
  * is an example target *
<ENDCODE_EXAMPLE>

<CP> as containing two matching wildcard strings

<CODE_EXAMPLE>
  this
  string
<ENDCODE_EXAMPLE>

<CP> which could be substituted using the result string

<CODE_EXAMPLE>
  * is an example result * 
<ENDCODE_EXAMPLE>

<CP> producing the resultant string

<CODE_EXAMPLE>
  this is an example result string
<ENDCODE_EXAMPLE>

<HEAD>(Regular Expression Substitution\head_string_matching_subs_regex)

<P> With regular expression matching the groups of matching characters must be
explicitly specified using the <EMPHASIS>(grouping) parenthesis operator. 
Hence with regular expression matching it is possible to match many characters
from the target string without retaining them for later substitution.  Only if
that match is designated as a subsitution source do the matching characters
become available for substituion via any result string.  Using two possible
target strings as an example

<CODE_EXAMPLE>
  this is an example target string
  this is a contrived target string
<ENDCODE_EXAMPLE>

<CP> would both be matched by the regular expression

<CODE_EXAMPLE>
  ^^([a-z]*) is [a-z ]* target ([a-z]*)$
<ENDCODE_EXAMPLE>

<CP> which though it contains three regular expressions in the pattern, only
two have the grouping parentheses, and so make their matching string available
for substitution

<CODE_EXAMPLE>
  this
  string
<ENDCODE_EXAMPLE>

<CP> which could be substituted using the result string

<CODE_EXAMPLE>
  * is the final result * 
<ENDCODE_EXAMPLE>

<CP> producing the resultant string

<CODE_EXAMPLE>
  this is the final result string
<ENDCODE_EXAMPLE>

<HEAD>(Specified Substitution\head_string_matching_subs_spec)

<P> By default the strings matched by wildcard or grouping operators are
substituted in the same order in which they are matched.  This order may be
changed by specifying which wildcard string should be substituted where.  Not
all matched (and stored) strings need to be substituted.  Some may be omitted
and the contents effectively ignored.

<P> The specified substitution syntax is a result wildcard followed by a
single-apostrophe (') and a single digit from zero to nine (0<HELLIPSIS>9). 
The zeroeth element is the full matching string.  Element one is the first
matching part of the expression, on through to the last.  Specifying an element
that had no matching string substitutes an empty string (i.e. nothing is
added).  Using the same target string as in the previous previous example

<CODE_EXAMPLE>
  this is an example target string
<ENDCODE_EXAMPLE>

<CP> and matched by the wildcard pattern string

<CODE_EXAMPLE>
  * is an example target *
<ENDCODE_EXAMPLE>

<CP> when substituted by the result string

<CODE_EXAMPLE>
  *'2 is an example result
<ENDCODE_EXAMPLE>

<CP> would produce the resultant string

<CODE_EXAMPLE>
  string is an example result
<ENDCODE_EXAMPLE>

<CP> with the string represented by the first wildcard effectively being
discarded.

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

<CHAPTER>(Conditional Configuration\chapter_conditional)

<P> Mapping (HTTPD$MAP) and authorization (HTTPD$AUTH) rules may be
conditionally applied depending on request, server or other charactersistics. 
These include

<LIST>(SIMPLE)

<LE> server host name, port
<LE> client IP address and host name
<LE> browser-accepted content-types, character sets, languages, encodings
<LE> browser identification string
<LE> scheme (<QUOTE>(http:) or <QUOTE>(https:), i.e. is it a secure request?)
<LE> HTTP method (GET, POST, etc.)
<LE> request path, query string, cookie data, refering page
<LE> virtual host:port specified in request header
<LE> system information (hardware, Alpha/VAX, node name, VMS version, etc.)
<LE> local time
<LE> random number generation

<ENDLIST>

<P> Conditionals may be nested up to a maximum depth of eight, are not case
sensitive and generally match via string comparison,
although some tests are performed as boolean operations, by converting the
conditional parameter to a number before comparison, and IP address parameters
will accept a network mask as well as a string pattern.

<HEAD>(String Matching\head_cond_pattern_matching)

<P> The basis of much conditional decision making is string pattern matching. 
Both wildcard and regular expression based pattern  matching is available
(<REFERENCE>(chapter_string_matching)).  Wildcard matching in conditional tests
is <EMPHASIS>(greedy).  Regular expression matching, in common with usage
throughout WASD, is differentiated from wildcard patterns using a leading
<QUOTE>(^) character.

<HEAD1>(Conditional Syntax\head_cond_syntax)

<P> Conditional expressions and processing flow structures may be used in the
following formats.  Conditional and rule text may be indented for clarifying
structure.

<CODE_EXAMPLE>
  <EMPHASIS>(if (<EMPHASIS>(condition))\BOLD) then apply rest of line

  <EMPHASIS>(if (<EMPHASIS>(condition))\BOLD)
     then apply one
     or more rules
     up until the corresponding <HELLIPSIS>
  <EMPHASIS>(endif\BOLD)

  <EMPHASIS>(if (<EMPHASIS>(condition))\BOLD)
     then apply one
     or more rules
  <EMPHASIS>(else\BOLD)
     apply one or more other rules
     up until the corresponding <HELLIPSIS>
  <EMPHASIS>(endif\BOLD)

  <EMPHASIS>(if (<EMPHASIS>(condition))\BOLD)
     then apply one
     or more rules
  <EMPHASIS>(elif (<EMPHASIS>(condition))\BOLD)
     apply one or more other rules
     in a sort or case statement
  <EMPHASIS>(else\BOLD)
     a possible default rule or rules
     up until the delimiting
  <EMPHASIS>(endif\BOLD)
<ENDCODE_EXAMPLE>

<P> Logical operators are also supported, in conjunction with precedence
ordering parentheses, allowing moderately complex compound expressions to be
applied in conditionals.

<LIST>(SIMPLE)

<LE> <EMPHASIS>(!\BOLD) logical negation
<LE> <EMPHASIS>(<AMPERSAND><AMPERSAND>\BOLD) logical AND 
<LE> <EMPHASIS>(<VBAR><VBAR>\BOLD) logical OR

<ENDLIST>

<P> There are two more conditional structures that allow previous decisions to
be reused.  These are <EMPHASIS>(unif) and the <EMPHASIS>(ifif).  The first
unconditionally includes rules regardless of the current state of execution. 
The second resumes execution only if the previous <EMPHASIS>(if) or
<EMPHASIS>(elif) expression was true.  The <EMPHASIS>(else) statement may also
be used after an <EMPHASIS>(unif) to continue only if the previous expression
was false.  The purpose of these constructs are to allow a single decision
statement to include both conditional and unconditional rules.

<CODE_EXAMPLE>
  <EMPHASIS>(if (<EMPHASIS>(condition))\BOLD)
     then apply one
     or more rules
  <EMPHASIS>(unif\BOLD)
     apply this block of rules
     unconditionally
  <EMPHASIS>(ifif\BOLD)
     applied only if the original
     if expression was evaulated as true
  <EMPHASIS>(unif\BOLD)
     apply another block of rules
     unconditionally
  <EMPHASIS>(else\BOLD)
     and this block of rules
     only if the original if was false
  <EMPHASIS>(endif\BOLD)
<ENDCODE_EXAMPLE>

<NOTE>(CAUTION)
Conditional syntax is checked at rule load time (either server startup or
reload).  Basic errors such as unknown keywords and unbalanced parentheses or
structure statements will be detected and reported to the corresponding Admin
Menu report and to the server process log.
Unless these reports are checked after modifying rule sets syntax errors may
result in unexpected mappings or access.  Although the server cannot determine
the correct intent of an otherwise syntactically correct conditional, if it
encounters an unexpected but detectable condition during processing it aborts
the request, supplying an appropriate error message.
<ENDNOTE>

<HEAD1>(Conditional Keywords\head_conditional_list)

<P> The following keywords provide a match between the corresponding request or
other value and a string immediately following the delimiting colon.  White
space or other reserved characters may not be included unless preceded by a
backslash.  The actual value being used in the conditional matching may be
observed using the mapping item of the WATCH facility
(<REFERENCE>(chapter_watch)).

<P>
<CENTER_LINE>(<EMPHASIS>(Conditional Keywords\BOLD))
<TABLE>
<TABLE_SETUP>(2\13)
<TABLE_HEADS>(Keyword\Description)

<TABLE_ROW>(accept:\
Browser-accepted content types as listed in the <QUOTE>(Accept:) request
header field.  Same string as provided in CGI variable HTTP_ACCEPT.)

<TABLE_ROW>(accept-charset:\
Browser-accepted character sets as listed in the <QUOTE>(Accept-Charset:)
request header field.  CGI variable HTTP_ACCEPT_CHARSET.)

<TABLE_ROW>(accept-encoding:\
Browser-accepted content encoding as listed in the
<QUOTE>(Accept-Encoding:) request header field.  CGI variable
HTTP_ACCEPT_ENCODING.)

<TABLE_ROW>(accept-language:\
Browser language preferences as listed in the
<QUOTE>(Accept-Language:) request header field.  CGI variable
HTTP_ACCEPT_LANGUAGE.)

<TABLE_ROW>(authorization:\
The raw authorization string from the request header, if any supplied. 
This could be simply used to test whether it has been supplied or not.)

<TABLE_ROW>(callout:\
Simple boolean value. If a script callout is in progress (see <QUOTE>(Scripting
Overview, CGI Callouts).) it is true, otherwise false.)

<TABLE_ROW>(client_connect_gt:\
An integer representing the current network connections (those currently being
processed plus those currently being <QUOTE>(kept alive)) for the particular
client represented by the current request.  If greater than this value returns
true, otherwise false.
See <REFERENCE>(head_client_concurrency).
)

<TABLE_ROW>(cluster_member:\
If the supplied node name is (perhaps currently) a member of the cluster (if
any) the server may be executing on.)

<TABLE_ROW>(command_line:\
The command line qualifiers and parameters used when the server image was
activated.)

<TABLE_ROW>(cookie:\
Raw cookie data as the text string provided in <QUOTE>(Cookie:) request
header field.  CGI variable HTTP_COOKIE.)

<TABLE_ROW>(decnet:\
Whether DECnet is active on the system and which version is available. 
This value will be 0 if not active, 4 if PhaseIV or 5 is PhaseV.)

<TABLE_ROW>(document_root:\
The DOCUMENT_ROOT CGI variable SET using the
<EMPHASIS>(map=root=<LITERAL>(<string>)) mapping rule.)

<TABLE_ROW>(forwarded:\
Proxy/gateway host(s) request forwarded by, as specified in request header
field <QUOTE>(Forwarded:).  CGI variable HTTP_FORWARDED.)

<TABLE_ROW>(host:\
The host (and optionally port) specified in request header <QUOTE>(Host:)
field.  This is used by all modern browsers to provide virtual host information
to the server.  CGI variable HTTP_HOST.)

<TABLE_ROW>(jpi_username:\
The account username the server is executing as.)

<TABLE_ROW>(mapped_path:\
The path resulting from mapping (phase 2 if script path involved) from which
the path-translated is derived.)

<TABLE_ROW>(notepad:\
Information (strings) stored using the SET <EMPHASIS>(notepad=) mapping rule.
See <REFERENCE>(head_conditional_notepad).)

<TABLE_ROW>(ods:\
Specified as 2 or 5 (Extended File System), or as SRI file name encoding
(MultiNet NFS and others) PWK encoding (PATHWORKS 4/5), ADS encoding
(Advanced Server / PATHWORKS 6), SMB encoding (Samba - same as ADS). )

<TABLE_ROW>(pass:\
A numeric value, 1 or 2, representing the first or second pass (if a script
component was parsed) through the path mapping rules.  Will be zero at other
times.)

<TABLE_ROW>(path-info:\
Path specified in the request line.  CGI variable PATH_INFO.)

<TABLE_ROW>(path-translated:\
VMS translation of path-info.  Available after rule mapping (i.e. during
authorization rule processing).)

<TABLE_ROW>(query-string:\
Query string specified in request line.  Same information as provided in
CGI variable QUERY_STRING.)

<TABLE_ROW>(rand:\
Value from a random number generator.  See <REFERENCE>(head_conditional_rand).)

<TABLE_ROW>(redirected:\
If a request has been internally redirected
(<REFERENCE>(head_map_rule_redirect)) this conditional will be non-zero.  Can
be used as a boolean or with a digit specified.)

<TABLE_ROW>(referer:\
URL of refering page as provided in <QUOTE>(Referer:) request header field. 
CGI variable HTTP_REFERER.)

<TABLE_ROW>(regex:\
Simple boolean value.  If configuration directive [RegEx] is enabled (and hence
regular expression string matching, <REFERENCE>(chapter_string_matching)) this
will be true.)

<TABLE_ROW>(remote-addr:\
Client IP address.  Same as provided as CGI variable REMOTE_ADDR.  As
with all IP addresses used for conditional testing this may be wildcard string
match or network mask expressed as <EMPHASIS>(address)/<EMPHASIS>(mask-length)
(see <REFERENCE>(head_conditional_host_addresses)).)

<TABLE_ROW>(remote-host:\
Client host name if name resolution enabled, otherwise the IP address (same
as <EMPHASIS>(remote-addr)).
CGI variable REMOTE_HOST.)

<TABLE_ROW>(request:\
Detect the presence of specific or unknown request fields.
See <REFERENCE>(head_conditional_request).)

<TABLE_ROW>(request-method:\
HTTP method (<QUOTE>(GET), <QUOTE>(POST), etc.) specified in the request
line.  CGI variable REQUEST_METHOD.)

<TABLE_ROW>(request-scheme:\
Request protocol as <QUOTE>(http:) or <QUOTE>(https:).   CGI variable
REQUEST_SCHEME.)

<TABLE_ROW>(restart:\
A numeric value, zero to maximum, representing the number of times path mapping
has been SET <EMPHASIS>(map=restart).   Can be used as a boolean or with a
digit specified.)

<TABLE_ROW>(script-name:\
After the first pass of rule mapping (script component resolution), or during
authorization processing, any script component of the request URI.)

<TABLE_ROW>(server-addr:\
The service IP address.  CGI variable SERVER_ADDR.
This may be wildcard string match or network mask expressed as
<EMPHASIS>(address)/<EMPHASIS>(mask-length).)

<TABLE_ROW>(server_connect_gt:\
An integer representing the current server network connections (those currently
being processed plus those currently being <QUOTE>(kept alive)).  If greater
than this value returns true, otherwise false.
)

<TABLE_ROW>(server_process_gt:\
An integer representing the current server requests in-progress.  If greater
than this value returns true, otherwise false.
)

<TABLE_ROW>(server-name:\
The (possibly virtual) server name.  This may or may not exactly match any
string provided via the <EMPHASIS>(host) keyword.  CGI variable SERVER_NAME.)

<TABLE_ROW>(server-port:\
The (possibly virtual) server port number.  CGI variable SERVER_PORT.)

<TABLE_ROW>(server-software:\
The server identification string, including the version.  For example
<QUOTE>(HTTPd-WASD/8.0.0 OpenVMS/AXP SSL).  CGI variable SERVER_SOFTWARE.)

<TABLE_ROW>(service:\
This is the composite server name plus port as
<EMPHASIS>(server-name):<EMPHASIS>(port).)

<TABLE_ROW>(ssl:\
Simple boolean value.  If request is via Secure Sockets Layer then this
will be true.)

<TABLE_ROW>(syi_arch_name:\
System information; CPU architecture of the server system, <QUOTE>(Alpha),
<QUOTE>(IA64) or <QUOTE>(VAX). )

<TABLE_ROW>(syi_hw_name:\
System information; hardware identification string, for example
<QUOTE>(AlphaStation 400 4/233).)

<TABLE_ROW>(syi_nodename:\
System information; the node name, for example <QUOTE>(KLAATU).)

<TABLE_ROW>(syi_version:\
System information; VMS version string, for example <QUOTE>(V7.3).)

<TABLE_ROW>(tcpip:\
A string derived from the UCX$IPC_SHR shareable image.
It looks something like this <QUOTE>(Compaq TCPIP$IPC_SHR V5.1-15
(11-JAN-2001 02:28:33.95)) and comprises the agent (Compaq, MultiNet, TCPware,
unknown), the name of the image, the version and finally the link date.)

<TABLE_ROW>(time:\
Compare to current system time.  See <REFERENCE>(head_conditional_time).)

<TABLE_ROW>(trnlnm:\
Translate a logical name.  See <REFERENCE>(head_conditional_trnlnm).)

<TABLE_ROW>(user-agent:\
Browser identification string as provided in <QUOTE>(User-Agent:) request
header field.  CGI variable HTTP_USER_AGENT. )

<TABLE_ROW>(x-forwarded-for:\
Proxied client name or address as provided in <QUOTE>(X-Forwarded-For:) request
header field.  CGI variable HTTP_X_FORWARDED_FOR.) 

<ENDTABLE>

<HEAD>(Notepad: Keyword\head_conditional_notepad)

<P> The <EMPHASIS>(request notepad) is a string storage area that can be used
to store and retrieve ad hoc information during path mapping and subsequent
authorization processing.  The notepad contents can be changed using the SET
<EMPHASIS>(notepad=<LITERAL>(<string>)) or appended to using SET
<EMPHASIS>(notepad=+<LITERAL>(<string>)) (<REFERENCE>(head_set_rules)).  These
contents then can be  subsequently detected using the <EMPHASIS>(notepad:)
conditional keyword (or the obsolescent 'NO' mapping conditional) and used to
control subsequent mapping or authorization processing.

<NOTE>
Notepad information persists across internal redirection processing
(<REFERENCE>(head_map_rule_redirect)) and so may be used when the regenerated
request is mapped and authorized.  To prevent such information from
unexpectedly interfering with internally redirected requests a
<EMPHASIS>(notepad=<QUOTE>()) can be used to empty the storage area.
<ENDNOTE>

<HEAD>(Rand: Keyword\head_conditional_rand)

<P> At the commencement of each pass a new pseudo-random number is generated
(and therefore remains constant during that pass).  The  <EMPHASIS>(rand:)
conditional is intended to allow some sort of distribution to be built into a
set of rules, where each pass (request) generates a different one.  The random
conditional accepts two parameters, a <EMPHASIS>(modulas) number, which is used
to modulas the base number, and a <EMPHASIS>(comparison) number, which is
compared to the modulas result.

<P> Hence the following conditional rules

<CODE_EXAMPLE>
  if (rand:3:0)
     <EMPHASIS>(do this)
  elif (rand:3:1)
     <EMPHASIS>(do this)
  else
     <EMPHASIS>(do this)
  endif
<ENDCODE_EXAMPLE>

<CP> would pseudo-randomly generate base numbers of 0, 1, 2 and perform the
appropriate conditional block.  Over a sufficient number of usages this should
produce a relatively even distribution of numbers.  If the modulas is specified
as less than two (i.e. no distribution factor at all) it defaults to 2 (i.e. a
distribution of 50%).  Hence the following example should be the equivalent of
a coin toss.

<CODE_EXAMPLE>
  if (rand:)
     <EMPHASIS>(heads)
  else
     <EMPHASIS>(tails)
  endif
<ENDCODE_EXAMPLE>

<HEAD>(Request: Keyword\head_conditional_request)

<P> Looks through each of the lines of the request header for the specified
request field and/or value.  This may be used to detect the presence of
specific or unknown (to the server) request fields.  When detecting a specified
just field the name can be provided

<CODE_EXAMPLE>
  if (request:"Keep-Alive:*")
<ENDCODE_EXAMPLE>

<CP> matching any value, or specific values can also be matched for

<CODE_EXAMPLE>
  if (request:"User-Agent:*Opera*")
<ENDCODE_EXAMPLE>

<P> Note that all request fields known to the server have a specific associated
conditional keyword (i.e. <QUOTE>(user-agent:) for the above example).  To
determine whether any request fields unknown to the server have been supplied
use the <EMPHASIS>(request:) keyword as in the following example.

<CODE_EXAMPLE>
  if (request:?)
     map * /cgi-bin/unknown_request_notify.com*
  endif
<ENDCODE_EXAMPLE>

<HEAD>(Time: Keyword\head_conditional_time)

<P> The <EMPHASIS>(time:) conditional allows server behaviour to change
according to the time of day, week, or even year.  It compares the supplied
parameter to the current system time in one of three ways.

<LIST>(NUMBERED)

<LE> The supplied parameter is in the form <QUOTE>(1200-1759), which should
be read as <QUOTE>(twelve noon to five fifty-nine PM) (i.e. as a time range in
minutes, generalized as <emphasis>(hhmm-hhmm)), where the first is the start
time and the second the end time.  If the current time is within that range
(inclusive) the conditional returns true, otherwise false.  If the range
doesn't look correct false is always returned.

<CODE_EXAMPLE>
  if (time:0000-0000)
     <EMPHASIS>(it's midnight)
  elif (time:0001-1159)
     <EMPHASIS>(it's AM)
  elif (time:1200-1200)
     <EMPHASIS>(it's noon)
  else
     <EMPHASIS>(it's PM)
  endif
<ENDCODE_EXAMPLE>

<LE> If the supplied parameter is a single digit it is compared to the VMS day
of the week (1-Monday, 2-Tuesday <HELLIPSIS> 7-Sunday).

<CODE_EXAMPLE>
  if (time:6 <VBAR><VBAR> time:7)
     <EMPHASIS>(it's the weekend)
  else
     <EMPHASIS>(it's the working week)
  endif
<ENDCODE_EXAMPLE>

<LE> If the supplied string is not in either of the formats described above it
is treated as a string match with a VMS comparision time (i.e.
<EMPHASIS>(yyyy-mm-dd hh-mm-ss.hh)). 

<CODE_EXAMPLE>
  if (time:%%%%-05-*)
     <EMPHASIS>(it's the month of May)
  endif
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(Trnlnm: Keyword\head_conditional_trnlnm)

<P> The <EMPHASIS>(trnlnm:) conditional dynamically translates a logical name
and uses the value.  One mandatory and up to two optional parameters may be
supplied.

<CODE_EXAMPLE>
  trnlnm:logical-name[;name-table][:string-to-match]
<ENDCODE_EXAMPLE>

<P> The <EMPHASIS>(logical-name) must be supplied; without it false is always
returned.  If just the <EMPHASIS>(logical-name) is supplied the conditional
returns true if the name exists or false if it does not.  The default
<EMPHASIS>(name-table) is LNM$FILE_DEV.  When the optional
<EMPHASIS>(name-table) is supplied the lookup is confined to that table.  If
the optional <EMPHASIS>(string-to-match) is supplied it is matched against the
value of the logical and the result returned.

<HEAD>(Host Addresses\head_conditional_host_addresses)

<P> Host names or addresses can be an alpha-numeric string (if DNS lookup is
enabled) or dotted-decimal network address, a slash, then a dotted-decimal
mask.  For example <QUOTE>(131.185.250.0/255.255.255.192). This has a 6 bit
subnet.  It operates 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. Equivalent notation
for this rule would be <QUOTE>(131.185.250.0/26).

<HEAD1>(Examples\head_conditional_examples)

<P> The following provides a collection of examples of conditional mapping and
authorization rules illustrating the use of wildcard matching, network mask
matching and the various formats in which the rules may be blocked.

<LIST>(NUMBERED)

<LE> This first example shows an EXEC mapping rule being applied to a path if
the request query string contains the string <QUOTE>(example).

<CODE_EXAMPLE>
  if (query-string:*example*) exec /* /cgi-bin/example/* 
<ENDCODE_EXAMPLE>

<LE> In this example a block of mapping statements is processed if the virtual
service of the request matches that in the conditional, otherwise the block is
skipped.  Note the indentation to help clarify the structure.

<CODE_EXAMPLE>
  if (service:the.host.name:80)
     pass /web/* /dka0/the_host_name_web/*
     pass /graphics/* /dka100/graphics/*
     pass * "404 Resource not found."
  endif
<ENDCODE_EXAMPLE>

<LE> This example a series of tests allow a form of case processing where the
first to match will be processed and terminate the matching process.  In this
case if a match does not occur rule processing continues after the
<EMPHASIS>(endif).

<CODE_EXAMPLE>
  if (service:the.host.name:80)
     pass /web/* /dka0/the_host_name_web/*
  elif (service:next.host.name:80)
     pass /web/* /dka0/next_host_name_web/*
  elif (service:another.host.name:80)
     pass /web/* /dka0/another_host_name_web/*
  endif
  pass /graphics/* /dka100/graphics/*
  pass * "404 Resource not found."
<ENDCODE_EXAMPLE>

<LE> In this (somewhat contrived) example a nested test is used to check
(virtual) server name and that the request is being handled via Secure Sockets
Layer (SSL) for security.  If it is not an informative message is supplied. 
The <EMPHASIS>(else) and the quotes are not really required but included here
for illustration.

<CODE_EXAMPLE>
  if (server-name:the.host.name)
     if (scheme:<QUOTE>(https))
        pass /secure/* /dka0/the_host_name_web/secure/*
     else
        pass * /dka0/the_host_name_web/secure/only-via-SSL.html
     endif
  endif
<ENDCODE_EXAMPLE>

<LE> This would be another way to accomplish a similar objective to example 4. 
This uses a <EMPHASIS>(negation) operator to exclude access to successive
mappings if not requesting via SSL.

<CODE_EXAMPLE>
  if (server-name:the.host.name)
     if (!SSL:)
        pass * /web/secure/only-via-SSL.html
     endif
     pass /secure/* /web/secure/*
     pass /other/* /web/other/*
     pass /web/* /web/web/*
     pass * "404 Resource not found."
  endif
<ENDCODE_EXAMPLE>

<LE> This example shows the use of a compound conditional using the AND and OR
operators.  It also illustrates the use of a network mask.  It will exclude all
access to the specified path unless the request is originating from
within a specified network (perhaps an intranet) or via SSL.

<CODE_EXAMPLE><LITERAL>
  if (path:/sensitive/* && !(remote-addr:131.185.250.0/24 || SSL:))
     pass * 404 "Access denied (SSL only)."
  endif
<ENDLITERAL><ENDCODE_EXAMPLE>

<LE> This example illustrates restricting authentication to SSL.

<CODE_EXAMPLE>
  [[*]]
  ["Your VMS password"=VMS]
  if (!request-scheme:https)
     * r+w,#0
  endif
<ENDCODE_EXAMPLE>

<LE> Logical name translation may be used to dynamically alter the flow of rule
interpretation.

<CODE_EXAMPLE>
  if (trnlnm:HTTPD_EXAMPLE)
     pass /* /example/*
  else
     pass /* /*
  endif
<ENDCODE_EXAMPLE>

<ENDLIST>

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

<CHAPTER>(Mapping Rules\chapter_mapping_rule)

<P> Mapping rules are used for a few different purposes.

<LIST>(NUMBERED)

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

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

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

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

<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> The [IncludeFile] is a directive common to all WASD configuration, allowing
a separate file to be included as a part of the current configuration
(<REFERENCE>(head_config_directives_include)).

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

<NOTE>(Checking Mapping Rules)
A server's currently loaded mapping rules may be interrogated.  See
<REFERENCE>(chapter_server_admin) for further information.  Also the Server
Administration facility allows realm and arbitrary  paths to be checked against
the rule database in real-time using the WATCH facility
(<REFERENCE>(chapter_watch)). In this way the rule database may be checked
against test or even live requests.
<ENDNOTE>

<P> Any subsequent changes to the mapping file may be reloaded into the running
HTTPd server using the following command on the server system: 

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

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

<HEAD1>(Rule Interpretation\head_map_rule_interp)

<P> The rules are scanned from first towards last, until a matching
final rule  is encountered (PASS, EXEC, SCRIPT, FAIL, REDIRECT, UXEC and USER)
when the mapping pass concludes.  Non-final rules (MAP and SET) perform the
appropriate action and continue to the next rule.  One, two or more passes
through the rules may occur due to implicit processing (if the path contains a
script component) or by explicit restart (SET <EMPHASIS>(map=restart)).

<HEAD>(String Matching\head_map_pattern_matching)

<P> The basis of path mapping is string pattern matching, comparing the request
specified path, and optionally other components of the request when using
configuration conditionals (<REFERENCE>(chapter_conditional)), to a series of
patterns, usually until one of the patterns matches, at which stage some
processing is performed.  Both wildcard and regular expression based pattern
matching is available.
  All rules have a <EMPHASIS>(template)
(string pattern to match against the path).  Some rules have a
<EMPHASIS>(result) (how to restructure the components matching from the
template).

<LIST>(UNNUMBERED)

<LE> The <EMPHASIS>(template\BOLD) may contain one or more asterisk
(<QUOTE>(*)) wildcard symbols, or a regular expression with optional grouping
operators.  This is pattern matched against the request path
(<REFERENCE>(chapter_string_matching)).  If neither is present then the path
must match the <EMPHASIS>(template) exactly. 

<LE> The <EMPHASIS>(result\BOLD) may contain one or more asterisk (<QUOTE>(*))
substitution symbols. The <EMPHASIS>(result) wildcards are expanded to replace
the matching strings of the respective <EMPHASIS>(template) wildcards or
pattern groups.  Specified wildcard substitution is available
(<REFERENCE>(head_string_matching_subs)).  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.

<HEAD>(Processing 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 Digital
AlphaStation 500/333 with 256MB, VMS V7.3-1, and WASD v8.3, with a simple
access to /ht_root/exercise/0k.txt showed approximately 108 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\108\baseline)
<TABLE_ROW>(100\104\-3.7%)
<TABLE_ROW>(200\100\-7.4%)
<TABLE_ROW>(500\91\-15.7%)
<TABLE_ROW>(1000\70\-35.1%)
<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 may
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 (<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 (<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> These are the categories of mapping rules.

<LIST>(UNNUMBERED)

<LE> Map paths to the file system, and to other paths:

<LIST>(SIMPLE)
<LE> MAP
<LE> PASS
<LE> FAIL
<LE> REDIRECT
<LE> USER
<ENDLIST>

<LE> Provide access to scripting:

<LIST>(SIMPLE)
<LE> EXEC
<LE> SCRIPT
<LE> UXEC
<ENDLIST>

<LE> Sets characteristics against particular paths:

<LIST>(SIMPLE)
<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>(/)).

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

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

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

<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 one of a number of 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.  A
<EMPHASIS>(result) may or may not contain a fixed query string
(<QUOTE>(/path/to/whatever?one=two)).

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

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

<LE> If the scheme is provided but no host component the current request's
host information 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. 

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

<NOTE>
Internal redirection (as this is termed) is a fundamental mechanism available
with WASD to completely change the request path and/or query string components
for the request - transparently to the client.  It is essentially a complete
rewrite of the request.
<ENDNOTE>

<LE> Only if the <UNDERLINE>(last) character in the <EMPHASIS>(result) is a
question mark (<QUOTE>(?)) will any query string in the original be propagated
into the redirection URL (that is the original request
<QUOTE>(/original/test.txt?plus=query) is mapped using <QUOTE>(redirect
/original/* /path/to/*?) does the resulting URL become
<QUOTE>(/path/to/test.txt?plus=query)).

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

<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-BIN] or
HT_ROOT:[VAX-BIN] (depending on the platform), and procedures, etc. in
HT_ROOT:[CGI-BIN].  These multiple directories are accessable via the single
search list logical CGI-BIN.

<P> Script files can be located in area completely outside of the HT_ROOT tree. 
Two approaches are available.

<LIST>(NUMBERED)

<LE> Modify the search list CGI-BIN to include the additional directories. 
Only should be done with extreme care.

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

<HEAD>(EXEC Directories and EXEC Files\head_map_rule_exec_dir_files)

<P> Generally directories are specified as locations for script files.  This is
the more common application, with the EXEC rules used as in this example

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

<P> Mapping a file type into an EXEC behaviour is also supported.  This allows
all files within the specified path and with the matching file suffix
(extension) to be activated as scripts.  Of course a script runtime must be
available for the server to be able activate it.  The following example
demonstrates mapping all files ending in .CGI in the /web/ tree as executable
scripts.

<CODE_EXAMPLE>
  exec /web/*.cgi* /web/*.cgi*
<ENDCODE_EXAMPLE>

<NOTE>(WARNING)
Remember scripts are <EMPHASIS>(executables\BOLD).  Enabling scripting in a
general user area allows <EMPHASIS>(any\BOLD) user to write and execute any
script, by default under the server account.  Deploy with discretion.
<ENDNOTE>

<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>(UNNUMBERED)

<LE><EMPHASIS>(ACCEPT=LANG=<EMPHASIS>(<LITERAL>(<parameter>)) -\BOLD)
Allows a path to be marked for language-variant document processing.

<LIST>(UNNUMBERED)
<LE> <QUOTE>(ACCEPT=LANG=DEFAULT=<EMPHASIS>(language)) sets the default
language
<LE> <QUOTE>(ACCEPT=LANG=CHAR=<EMPHASIS>(character)) sets the delimiting
character
<LE> <QUOTE>(ACCEPT=LANG=VARIANT=<EMPHASIS>(name<VBAR>type)) allows the
alternate file-type variant to be specified
<LE>
<QUOTE>(ACCEPT=LANG=(DEFAULT=<EMPHASIS>(language),CHAR=<EMPHASIS>(character))) 
sets both (etc.)
<LE> <QUOTE>(NOACCEPT=LANG) disables language variant processing (on a subtree
for example)
<ENDLIST>

<P> For detailed configuration information see
<REFERENCE>(head_language_variants).

<LE><EMPHASIS>(ALERT[=<EMPHASIS>(<LITERAL>(<keyword>))] -\BOLD)
Marks a path as being of specific interest.  When a request containing this
path is detected by the server it puts a message into the the server process
log and perhaps of greater immediate usefulness the increase in alert hits is
detected by HTTPDMON and this (optionally) provides an audible alert.  The
following is ordered according to how early in processing the alert is
signalled.

<LIST>(UNNUMBERED)
<LE> <QUOTE>(ALERT=MAP)
generates this alert immediately after path mapping (i.e. before the request
actually begins being processed).
<LE> <QUOTE>(ALERT=AUTH)
after authorization (i.e. when any remote username has been resolved).
<LE> <QUOTE>(ALERT=END)
at the conclusion of process (the default).
<LE> <QUOTE>(ALERT=<EMPHASIS>(integer))
if the response HTTP status matches the specific integer.
<LE> <QUOTE>(NOALERT)
cancels alerts on this path (perhaps subpath).
<ENDLIST>

<LE><EMPHASIS>(AUTH=<EMPHASIS>(<LITERAL>(<keyword>)) -\BOLD)
Changes the specified characteristic during subsequent authorization
processing.

<LIST>(UNNUMBERED)

<LE><QUOTE>([NO]AUTH=ALL)
All requests matching this path must have been subject to authorization or fail
with a forbidden status.  This is a per-path requivalent of implementing the
per-server /AUTHORIZE=ALL policy (<REFERENCE>(head_auth_all_requests)), and is
a little <QUOTE>(belt and braces) in a certain sense, but does permit a site to
further avoid unintended information leakage (in this case through the failure
ensure a given path has authorization).

<LE><QUOTE>([NO]AUTH=ONCE)
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 (<REFERENCE>(chapter_authorization)).  This can be disabled using
this path setting.  When this is done only the original request path undergoes
authorization.

<LE><QUOTE>(AUTH=REVALIDATE=<EMPHASIS>(<LITERAL>(<hh:mm:ss>)))
Authorization is cancelled and the client requested to reenter the username and
password if this period expires between authorized requests.  Overrides
configuration directive [AuthRevalidateUserMinutes].

<LE><QUOTE>(AUTH=SYSUAF=PWDEXPURL=<EMPHASIS>(<LITERAL>(<string>)))
Parallels the [AuthSysUafPwdExpURL] configuration directive, allowing it to be
set on a per-path or virtual service basis
(<REFERENCE>(head_auth_user_password_change)).

<ENDLIST>

<LE><EMPHASIS>(CACHE=<EMPHASIS>(<LITERAL>(<keyword>)) -\BOLD)
The default is to cache files (when caching is enabled,
<REFERENCE>(chapter_cache)).

<LIST>(UNNUMBERED)
<LE> <QUOTE>(CACHE=NONE) disables caching of files matching this rule
<LE> <QUOTE>(CACHE=EXPIRES=0) cancels previous mapped expiry
<LE> <QUOTE>(CACHE=EXPIRES=DAY) expires on change of day
<LE> <QUOTE>(CACHE=EXPIRES=HOUR) expires on change of hour
<LE> <QUOTE>(CACHE=EXPIRES=MINUTE) expires on change of minute
<LE> <QUOTE>(CACHE=EXPIRES=<EMPHASIS>(<LITERAL>(<period>))) sets the expiry
period for the entry
<LE> <QUOTE>(CACHE=GUARD=<EMPHASIS>(<LITERAL>(<period>))) sets the guard period
(no reload) for the cache entry
<LE> <QUOTE>(CACHE=MAX=<EMPHASIS>(<LITERAL>(<integer>))) cache files up to this 
many kilobytes (overrides [CacheFileKBytesMax]))
<LE> <QUOTE>(CACHE=[NO]CGI) cache CGI-compliant (script) responses
<LE> <QUOTE>(CACHE=[NO]FILE) cache files matching this rule (the default)
<LE> <QUOTE>(CACHE=[NO]NET) cache any network output
<LE> <QUOTE>(CACHE=[NO]NPH) cache NPH (non-parse-header script) responses
<LE> <QUOTE>(CACHE=[NO]SCRIPT) cache both CGI and NPH responses
<LE> <QUOTE>(CACHE=[NO]SSI) cache SSI document responses
<LE> <QUOTE>(CACHE=[NO]QUERY) cache (script) regardless of containing a query
string
<LE> <QUOTE>(CACHE=[NO]PERM) permanently cache these files
<ENDLIST>

<LE><EMPHASIS>(CGIPLUSIN=<EMPHASIS>(<LITERAL>(<keyword>)) -\BOLD)
Provides control over how CGIplus records on the CGIPLUSIN stream are carriage
controlled and how the stream is terminated.  A little esoteric certainly; ask
Alex Ivanov ;^)

<LIST>(UNNUMBERED)
<LE> <QUOTE>(CGIPLUSIN=CC=NONE) no carriage control
<LE> <QUOTE>(CGIPLUSIN=CC=LF) each record has a trailing line feed (0x0a)
<LE> <QUOTE>(CGIPLUSIN=CC=CR) a trailing carriage return (0x0d)
<LE> <QUOTE>(CGIPLUSIN=CC=CRLF) a trailing line feed then carriage return
(0x0d0a)
<LE> <QUOTE>(CGIPLUSIN=[NO]EOF) the end of the record stream is indicated
using an end-of-file
<ENDLIST>

<LE><EMPHASIS>(CGIPREFIX=<EMPHASIS>(<LITERAL>(<string>)) -\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=).

<LE><EMPHASIS>(CHARSET=<EMPHASIS>(<LITERAL>(<string>)) -\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).

<LE><EMPHASIS>(CONTENT=<EMPHASIS>(<LITERAL>(<string>)) -\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).

<LE><EMPHASIS>(DIR=<EMPHASIS>(<LITERAL>(<keyword>)) -\BOLD)
Allows directory listing to be controlled on a per path basis.  These
parallel the coresponding configuration [Dir..] directives.

<LIST>(UNNUMBERED)
<LE> <QUOTE>(DIR=[NO]ACCESS) allows directory listing
<LE> <QUOTE>(DIR=ACCESS=SELECTIVE) allows directory listing if the directory
contain the file .WWW_BROWSABLE
<LE> <QUOTE>(DIR=[NO]IMPLIEDWILDCARD) add wildcards if not in path
<LE> <QUOTE>(DIR=STYLE=) set the style of a directory listing
<LIST>(UNNUMBERED)
<LE> <QUOTE>(ANCHOR) the current and default WASD style (post-v8.2)
<LE> <QUOTE>(DEFAULT) the current WASD style (post-v8.2)
<LE> <QUOTE>(ORIGINAL) the traditional (pre-v8.2)
<LE> <QUOTE>(HTDIR) Alex Ivanov's HTdir style
<ENDLIST>
<LE> <QUOTE>(DIR=[NO]WILDCARD) allow a directory listing to be <QUOTE>(forced)
by including wildcards in the path
<ENDLIST>

<P> For detailed configuration information see
<REFERENCE>(head_language_variants).

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

<LE><EMPHASIS>(HTML=<EMPHASIS>(<LITERAL>(<keyword>)=<LITERAL>(<string>)) -\BOLD)
Allows the <LITERAL>(<BODY>) tag, and header and/or footer characteristics and
text to be added to selected server generated pages such as directory listings
and error messages.

<LIST>(UNNUMBERED)
<LE> <QUOTE>(HTML=BODYTAG=) specifies the page <LITERAL>(<BODY>) tag
characteristics (e.g. html=bodytag=<QUOTE>(BGCOLOR=#ffffff))
<LE> <QUOTE>(HTML=HEADER=) the page header text
<LE> <QUOTE>(HTML=HEADERTAG=) the <LITERAL>(<TD>) tag characteristics of the
header table (e.g. html=headertag=<QUOTE>(BGCOLOR=#cccccc))
<LE> <QUOTE>(HTML=FOOTER=) the page footer text
<LE> <QUOTE>(HTML=FOOTERTAG=) the <LITERAL>(<TD>) tag characteristics of the
footer table
<ENDLIST>

<P> The <EMPHASIS>(headertag) and <EMPHASIS>(footertag) directives also allow
the full table tag to be specified, allowing greater flexibility with these
parts of the page (e.g. html=footertag=<QUOTE>(<LITERAL>(<TABLE BORDER=1
CELLPADDING=10 CELLSPACING=0><TR><TD BGCOLOR=#cccccc>)).

<LE><EMPHASIS>(HTTP=<EMPHASIS>(<LITERAL>(<parameter>)) -\BOLD)
Explicitly sets an aspect of the HTTP request header.

<LIST>(UNNUMBERED)

<LE><QUOTE>(HTTP=ACCEPT-CHARSET=<EMPHASIS>(<LITERAL>(<string>)))
the <QUOTE>(Accept-Charset:) field

<LE><QUOTE>(HTTP=ACCEPT-LANGUAGE=<EMPHASIS>(<LITERAL>(<string>)))
the <QUOTE>(Accept-Language:) field

<ENDLIST>

<LE><EMPHASIS>(INDEX=<EMPHASIS>(<LITERAL>(<string>)) -\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.

<LE><EMPHASIS>([NO]LOG -\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.

<LE><EMPHASIS>(MAP=<EMPHASIS>(<LITERAL>(<parameter>)) -\BOLD)
Controls aspects of the mapping processing itself (from that point in the rules
onwards of course).

<LIST>(UNNUMBERED)

<LE><QUOTE>([NO]MAP=ELLIPSIS)
By default the use of the VMS file specification ellipsis wilcard
(<QUOTE>(...)) is not allowed.  This enables this for the path specified.  Use
with caution.

<LE><QUOTE>([NO]MAP=ONCE)
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 MAP=ONCE.  The resultant path is then given to the script without
further processing.

<LE><QUOTE>(MAP=RESTART)
Causes an immediate change to the order of rule processing.  Instead of the
next rule, the first rule in the configuration is processed.  This is intended
to remove the need for copious repetition in the rule set.  A common or set of
common processing blocks can be established near the start of the rule set and
be given requests from processing from points further down in the rules.  It is
intended to be used only once or perhaps twice and will abort the request if it
occurs too often.  Can be detected using the <EMPHASIS>(restart:) conditional
(<REFERENCE>(head_conditional_list)).  Use with caution!  Injudicious use
would make unexpected mappings expected!

<LE><QUOTE>([NO]MAP=ROOT=<EMPHASIS>(<LITERAL>(<string>)))
Prefixes the results of following rules with the specified path so that they
are all subordinate to it.  This also populates the DOCUMENT_ROOT CGI variable.
See <REFERENCE>(head_data_area_root).

<LE><QUOTE>([NO]MAP=SET=IGNORE)
All path SETings following an IGNORE are completely ignored (not applied to the
mapping or request characteristics) until a subsequent NOINGORE is encountered.

<LE><QUOTE>([NO]MAP=SET=REQUEST)
All path SETings following a NOMAP=SET=REQUEST are only applied to the mapping
and not to the request's characteristics until a subsequent MAP=SET=REQUEST is
encountered.  Intended for use during callouts.  These can be detected using
the <EMPHASIS>(callout:) conditional (<REFERENCE>(head_conditional_list)). 

<ENDLIST>

<LE><EMPHASIS>(NOTEPAD=[+]<EMPHASIS>(<LITERAL>(<string>)) -\BOLD)
The <EMPHASIS>(request notepad) is a string storage area that can be used to
store and retrieve ad hoc information during path mapping and subsequent
authorization processing.  Multiple <EMPHASIS>(notepad=string) set against the
one request override previous settings unless preceded by a leading plus
symbol, when it appends.  These contents then can be subsequently detected
using the <EMPHASIS>(notepad:) conditional keyword
(<REFERENCE>(head_conditional_notepad)) or the obsolescent 'NO' mapping
conditional.

<LE><EMPHASIS>(ODS=<EMPHASIS>(<LITERAL>(<keyword>)) -\BOLD) Directs the
server on how to process file names for naming conventions other than ODS-2
(the default).  Be sure to add an asterisk at the end of the specific ODS path
otherwise only the top-level will set!

<LIST>(UNNUMBERED)
<LE> <QUOTE>(ODS=2)
is basically redundant, because if a path is not indicated as anything else it
is assumed to be ODS-2.  This can be used for clarity in the mapping rules if
required.
<LE> <QUOTE>(ODS=5)
is used to indicate that a particular path maps to files on an ODS-5 (EFS)
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 below).
<LE> <QUOTE>(ODS=ADS)
is used to process file names that are encoded using the Advanced Server
(PATHWORKS 6) schema.
<LE> <QUOTE>(ODS=PWK)
is used for processing file names encoded using the PATHWORKS 4/5 schema.
<LE> <QUOTE>(ODS=SMB)
is a synonym for ODS=ADS and makes clear the path is also being served by
Samba.
<LE> <QUOTE>(ODS=SRI)
for file names encoded using the SRI schema (used by MultiNet and TCPware NFS,
FTP and other utilities). 
<ENDLIST>

<LE><EMPHASIS>(QUERY-STRING=<EMPHASIS>(<LITERAL>(<string>)) -\BOLD)
Set the request's query string to that specified in the directive.  Overloads
any current query string.  Specify URL-encoded if the characters require it.

<LE><EMPHASIS>(PROXY=<EMPHASIS>(<LITERAL>(<parameter>)) -\BOLD)
Sets an aspect of proxy request processing.

<LIST>(UNNUMBERED)

<LE><QUOTE>(PROXY=BIND=<EMPHASIS>(<LITERAL>(<IP-address>)))
makes outgoing proxy requests appear to originate from this IP address.  Must
be an address that the media can be bound to.

<LE><QUOTE>(PROXY=CHAIN=<EMPHASIS>(<LITERAL>(<host:port>)))
makes outgoing proxy requests chain to this up-stream proxy server.

<LE><QUOTE>(PROXY=FORWARDED)
controls generatation a proxy <QUOTE>(Forwarded:) request field.  This optional
field contains information on the proxy server and as a further option the
client name or IP address.

<LIST>(UNNUMBERED)

<LE><QUOTE>(PROXY=NOFORWARDED) disables

<LE><QUOTE>(PROXY=FORWARDED[=BY]) contains the <EMPHASIS>(by) component.

<LE><QUOTE>(PROXY=FORWARDED=FOR) contains <EMPHASIS>(by) and the
<EMPHASIS>(for) components (client host name)

<LE><QUOTE>(PROXY=FORWARDED=ADDRESS) contains <EMPHASIS>(by) and the
<EMPHASIS>(for) components (client host address)

<ENDLIST>

<LE><QUOTE>(PROXY=REVERSE=LOCATION=<LITERAL>(string)) rewrites the
matching <QUOTE>(Location:) header field URL of a 302 response from an
internal, reverse-proxied server.

<LE><QUOTE>(PROXY=REVERSE=[NO]VERIFY)
sets a specialized authorization capability.
<LINE> See

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

<COMMENT>(HTML=
<A HREF="/ht_root/src/httpd/proxyverify.c">HT_ROOT:[SRC.HTTPD]PROXYVERIFY.C</A>)

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

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

for further information.

<LE><QUOTE>(PROXY=XFORWARDEDFOR=)
controls generation of a proxy <QUOTE>(X-Forwarded-For:) request field.  This
optional field (a defacto standard originally from the <EMPHASIS>(Squid)
caching package) contains the name or IP address of the proxied client.

<LIST>(UNNUMBERED)

<LE><QUOTE>(PROXY=NOXFORWARDEDFOR) disables

<LE><QUOTE>(PROXY=XFORWARDEDFOR[=ENABLED]) enables

<LE><QUOTE>(PROXY=XFORWARDEDFOR=ADDRESS) field contains client host address

<LE><QUOTE>(PROXY=XFORWARDEDFOR=UNKNOWN) field contains
<EMPHASIS>(unknown) for the client host name

<ENDLIST>

<ENDLIST>

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

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

<LIST>(UNNUMBERED)
<LE> <QUOTE>(REPORT=BASIC) include less detail in error message
<LE> <QUOTE>(REPORT=DETAILED) includes more detail
<LE> <QUOTE>(REPORT=4<EMPHASIS>(nn)=<EMPHASIS>(nnn)) maps one 400 class HTTP
status to another (to conceal the true origins of some error messages)
<ENDLIST>

<LE><EMPHASIS>(RMSCHAR=<EMPHASIS>(<LITERAL>(<character>)) -\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=_).

<LE><EMPHASIS>(RESPONSE=HEADER=<EMPHASIS>(<LITERAL>(<parameter>)) -\BOLD)
changes the way in which a response header is generated by the server.

<LIST>(UNNUMBERED)

<LE><QUOTE>(RESPONSE=HEADER=BEGIN) suppresses the response header terminating
empty line so that the file or other resource can supply additional header
fields.  It, of course, must supply the header-terminating empty line before
beginning to supply the response body.

<LE><QUOTE>(RESPONSE=HEADER=FULL) reverts to normal response header generation
behaviour.

<LE><QUOTE>(RESPONSE=HEADER=NONE) suppresses the normal response header
generation.  It is considered the file or other resource contains and will
supply the full HTTP response (in a non-parse-header script fashion).

<LE><QUOTE>(RESPONSE=HEADER=ADD=<EMPHASIS>(<LITERAL>(<string>))) appends the
specified string to the response header.  Of course the string should be a
legitimate HTTP response field and value line.  This mapping can be used to add
a particular response directive to matching requests.

<ENDLIST>

<LE><EMPHASIS>(SCRIPT=<EMPHASIS>(<LITERAL>(<parameter>)) - \BOLD)
Provides controls over various aspects of the scripting environment.

<LIST>(UNNUMBERED)

<LE><QUOTE>(SCRIPT=AS=<EMPHASIS>(<LITERAL>(<parameter>)))
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).

<LE><QUOTE>(SCRIPT=BIT-BUCKET=<EMPHASIS>(<LITERAL>(<hh:mm:ss>)))
specifies the period for which a script continues to execute if the client
disconnects.  Overrides the HTTPD$CONFIG [DclBitBucketTimeout] configuration
directive.  For further detail see the <QUOTE>(Scripting Overview,
Introduction).

<LE><QUOTE>(SCRIPT=COMMAND=<EMPHASIS>(<LITERAL>(<string>)))
allows additional parameters and qualifiers to be passed to the script
activation command line.  First parameter must be an asterisk to use the server
resolved script command.  If the first parameter is not an asterisk it
substitues for the script activation verb.  Subsequent parameters must be as
they would be used on the command line.  The following setting

<CODE_EXAMPLE>
  set /cgi-bin/example* script=command="* /ONE /TWO=THREE FOUR"
<ENDCODE_EXAMPLE>

<CP> would result in the hypothetical script being command-line activated

<CODE_EXAMPLE>
  $ EXAMPLE /ONE /TWO=THREE FOUR
<ENDCODE_EXAMPLE>

<LE><QUOTE>(SCRIPT=CPU=<EMPHASIS>(<LITERAL>(<hh:mm:ss>)))
specifies that the server should not allow the script to use more than the
specified quantity of CPU time.  This is approximate, due to the way the server
administers scripting.  It can serve to prevent scripts from consuming
indefinite quantities of system resources.

<LE><QUOTE>(SCRIPT=DEFAULT=<EMPHASIS>(<LITERAL>(<string>)))
sets the default directory for the script environment (a SET DEFAULT
immediately prior to script activation).  This can be suppressed (for backward
compatibility purposes) using a <QUOTE>(#) as the target directory. This string
is reflected in CGI variable SCRIPT_DEFAULT so that CGIplus script and RTE
engines can be informed of this setting for a particular script's environment.
Unix syntax paths may also be specified.  If the default begins with a
<QUOTE>(/) character the SET DEFAULT is not performed but the SCRIPT_DEFAULT
variable is set appropriately allowing the equivalent of a <EMPHASIS>(chdir())
to be performed by the scripting environment. 

<LE><QUOTE>([NO]SCRIPT=FIND)
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.

<LE><QUOTE>(SCRIPT=PARAM=<EMPHASIS>(<LITERAL>((<name=value>))))
allows non-CGI environment variables to be associated with a particular
script path.  The name component becomes a variable containing the specified
value passed to the script.  Multiple, comma-separated <EMPHASIS>(name=value) 
pairs may be specified.  The value may be quoted.  The following path setting

<CODE_EXAMPLE>
  set /cgi-bin/example* script=params=(first=one,second="Two (and Three)")
<ENDCODE_EXAMPLE>

<CP> would result in additional CGI variables available to the script

<CODE_EXAMPLE>
  WWW_FIRST == "one"
  WWW_SECOND == "Two (and Three)"
<ENDCODE_EXAMPLE>

<P> Multiple <EMPHASIS>(script=params) set against the one request override
previous settings unless the parameters are specified with a leading plus
symbol, as in

<CODE_EXAMPLE>
  set /cgi-bin/example* script=params=+(third=three,fourth="number 4")
<ENDCODE_EXAMPLE>

<P> For futher information see the <QUOTE>(Scripting Overview, CGI).

<LE><QUOTE>([NO]SCRIPT=PATH=FIND) directs the server to check for and report if
the file specified in the path does not exist before activating the script
process.  Normally this would be left up to the script.

<LE><QUOTE>([NO]SCRIPT=QUERY=NONE) saves a small amount of overhead by suppressing
the decomposition of any query string into key or form fields for those
environments that do this for themselves.

<LE><QUOTE>([NO]SCRIPT=QUERY=RELAXED)
normally when the CGI variables are being prepared for a script and the query
string is parsed an error is reported if it uses
<EMPHASIS>(x-www-form-urlencoded) format and the encoding contains an error. 
However some scripts use non-strict encodings and this rule allows those
scripts to receive the query strings without the server complaining first.

<ENDLIST>

<LE><EMPHASIS>([NO]SEARCH=NONE -\BOLD)
Do not activate the automatic document search script for any query strings
associated with this path.

<LE><EMPHASIS>(SSI=<EMPHASIS>(<LITERAL>(<parameter>)) - \BOLD)
Controls aspects of Server-Side Include engine behaviour.

<LIST>(UNNUMBERED)

<LE><QUOTE>([NO]SSI=PRIV)
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, NOSSI=priv 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.

<LE><QUOTE>(SSI=EXEC=<EMPHASIS>(<LITERAL>(<string>)))
where <LITERAL>(<string>) is a comma-separated list of the #dcl parameters
permitted for the path allows fine-grained control of what capabilities are
enabled.  The parameter <QUOTE>(#) enables SSI on a per-path basis.

<CODE_EXAMPLE>
  ssi=exec=say,show
  ssi=exec=#
<ENDCODE_EXAMPLE>

<ENDLIST>

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

<LIST>(UNNUMBERED)
<LE> <QUOTE>(NOSSLCGI) disables the facility
<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.

<LE><EMPHASIS>([NO]STMLF -\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).

<LE><EMPHASIS>(THROTTLE=<EMPHASIS>(<LITERAL>(<parameter>)) -\BOLD)
Controls the concurrent number of scripts being processed on the path.

<LIST>(UNNUMBERED)
<LE> <QUOTE>(THROTTLE=<EMPHASIS>(n,[n,n,n,hh:mm:ss,hh:mm:ss]))
<LE> <QUOTE>(THROTTLE=FROM=<EMPHASIS>(n))
<LE> <QUOTE>(THROTTLE=TO=<EMPHASIS>(n))
<LE> <QUOTE>(THROTTLE=RESUME=<EMPHASIS>(n))
<LE> <QUOTE>(THROTTLE=BUSY=<EMPHASIS>(n))
<LE> <QUOTE>(THROTTLE=TIMEOUT=QUEUE=<EMPHASIS>(hh:mm:ss))
<LE> <QUOTE>(THROTTLE=TIMEOUT=BUSY=<EMPHASIS>(hh:mm:ss))
<ENDLIST>

<P> See <REFERENCE>(head_request_throttling).

<LE><EMPHASIS>(TIMEOUT=<EMPHASIS>(<LITERAL>(<parameter>)) -\BOLD)
Sets the appropriate timeout period on a per-path basis.

<LIST>(UNNUMBERED)
<LE> <QUOTE>(TIMEOUT=<EMPHASIS>(hh:mm:ss,hh:mm:ss,hh:mm:ss))
<LE> <QUOTE>(TIMEOUT=KEEPALIVE=<EMPHASIS>(hh:mm:ss))
<LE> <QUOTE>(TIMEOUT=NOPROGRESS=<EMPHASIS>(hh:mm:ss))
<LE> <QUOTE>(TIMEOUT=OUTPUT=<EMPHASIS>(hh:mm:ss))
<ENDLIST>

<P> The composite directive has the order <EMPHASIS>(keep-alive) then
<EMPHASIS>(no-progress) then <EMPHASIS>(output).
These parallel the respective configuration timeout periods.
See <REFERENCE>(head_config_directives_alpha).

<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/*
  # throttle this script's execution, 5 executing, unlimited waiting
  set /cgi-bin/big_script* throttle=5
  # disable server script search for this RTE
  set /onerte/*  script=nofind
  exec /onerte/* (CGI-BIN:[000000]ONERTE.EXE)/ht_root/src/one/*
<ENDCODE_EXAMPLE>

<HEAD>(Postfix SET Rule\head_set_rules_postfix)

<P> Path SETings may appended to any rule that contains both a template and
result.  This makes it possible to apply path SETings using matching final
rules.  For example a matching PASS rule does not require a separate, preceding
SET rule containing the same path to also apply required SETings.  This is more
efficient (requiring less pattern matching) and tends to make the rule set less
cluttered.

<CODE_EXAMPLE>
  # examples of postfix SET rule usage
  # ----------------------------------
  # if a request has "/plain-text/" in it's path then ALWAYS return as plain-text!
  map /*/plain-text/* /*/* content=text/plain
  # same for "/binary/"
  map /*/binary/* /*/* content=text/plain
  # indicate extended file specifications on this path
  pass /Documents/* /ods5_device/Documents/* ODS=5
  # throttle this script's execution, 5 executing, unlimited waiting
  script /cgi-bin/big_script* throttle=5
<ENDCODE_EXAMPLE>

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

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

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

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

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

<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.domain.name:80]]
  # ALPHA is the only service allowing access to VMS help directory
  pass /sys$common/syshlp/*
  [[beta.domain.name: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 /httpd/-/errorreportalpha.shtml  
  [[gamma.domain.name: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 /httpd/-/errorreport.shtml  
  # now the base directories for all documents
  [[alpha.domain.name:80]]
  /* /web/alpha/*
  [[beta.domain.name:80]]
  /* /web/beta/*
  [[gamma.domain.name:80]]
  /* /web/gamma/*
  [[*]]
  # catch-all rule (just in case :^)
  pass /* /web/*
<ENDCODE_EXAMPLE>

<P> The Server Administration page WATCH report
(<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>
<NOTE>((Somewhat) Deprecated and Discouraged)
There is now a more versatile approach to achieving the same functionality
described in this section, see <REFERENCE>(chapter_conditional).  Conditional
mapping will be retained for the foreseeable future with this documentation
available for reference by older site configurations.  The two approaches may
be used concurrently as required.
<ENDNOTE>

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

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

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

<LIST>(SIMPLE)

<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> Both wildcard and regular expression pattern matching is available
(<REFERENCE>(chapter_string_matching)).  Characters reserved for delimiting the
conditional must be backslash-escaped (spaces, TABs, wildcards and the
delimiting <QUOTE>([) and <QUOTE>(])).

<P>
<CENTER_LINE>(<EMPHASIS>(Mapping Conditionals\BOLD))
<TABLE>
<TABLE_SETUP>(2\10)
<TABLE_HEADS>(Conditional\Description)

<TABLE_ROW>(ac:\browser-accepted content types
(<QUOTE>(Accept:) request header field))
<TABLE_ROW>(al:\browser-accepted languages
(<QUOTE>(Accept-Language:) request header field))
<TABLE_ROW>(as:\browser-accepted character sets
(<QUOTE>(Accept-Charset:) request header field))
<TABLE_ROW>(ck:\cookie data
(<QUOTE>(Cookie:) request header field))
<TABLE_ROW>(ex:\extended file specification (boolean))
<TABLE_ROW>(fo:\request forwarded by proxy/gateway host(s)
(<QUOTE>(Forwarded:) request header field))
<TABLE_ROW>(ho:\browser host internet name or address)
<TABLE_ROW>(hm:\browser host internet address compare to
dotted-decimal and mask) 
<TABLE_ROW>(me:\request HTTP method)
<TABLE_ROW>(mp:\derived map path (after SCRIPT or MAP rule))
<TABLE_ROW>(no:\<QUOTE>(notepad) contents)
<TABLE_ROW>(pa:\first or second pass (after script resolution), as '1' or '2')
<TABLE_ROW>(pi:\path information)
<TABLE_ROW>(qs:\query string)
<TABLE_ROW>(rc:\internally redirected count, as '0', '1', '2' ..)
<TABLE_ROW>(rf:\refering page
(<QUOTE>(Referer:) request header field))
<TABLE_ROW>(ru:\request URI (non-URL-decoded path))
<TABLE_ROW>(sc:\request <EMPHASIS>(scheme) (protocol),
<QUOTE>(http), and if SSL is in use <QUOTE>(https) (<REFERENCE>(chapter_ssl)))
<TABLE_ROW>(sn:\server name)
<TABLE_ROW>(sp:\server port)
<TABLE_ROW>(st:\script name (after first pass script resolution))
<TABLE_ROW>(ua:\browser
(<QUOTE>(User-Agent:) request header field))
<TABLE_ROW>(vs:\virtual host and port request directed to
(<QUOTE>(Host:) request header field))
<TABLE_ROW>(xf:\proxied client
(<QUOTE>(X-Forwarded-For:) request header field))

<ENDTABLE>

<HEAD>(Examples\head_mapping_cond_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>

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

<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 /httpd/-/* /web/SorryNoAccess.html [!ho:131.185.250.201]
<ENDCODE_EXAMPLE>

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

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

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

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

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

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

<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 page.
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
(<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
(<REFERENCE>(head_server_reports)) and is implicitly flushed when the server's 
rules are reloaded (<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>(--------------------------------------------------------------------)
