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

<CHAPTER>(HTTPd Web Update\chapter_web_update)

<P> The <EMPHASIS>(Upd\bold)ate facility allows Web documents and file
environments to be administered from a standard browser.  This capability is
available to Web administrator and user alike.  Availability and capability
depends on the authorization environment within the server.

<P> It <EMPHASIS>(should be stressed\BOLD) that this is not designed as a full
hypertext administration or authoring tool, and for document preparation
relies on the editing capabilities of the <LITERAL>(<TEXTAREA>) widget of the
user's browser. It does however, allow <EMPHASIS>(ad-hoc changes\BOLD) to be
made to documents fairly easily, as well as allowing documents to be deleted,
and directories to be created and deleted.

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

<COMMENT>(HTML=
<P> Consult the 
<A HREF="/httpd/-/updhelp.html">current <B>Upd</B>ate documentation</A> for
usage detail.

<P> Here is <A HREF="/upd/ht_root/">an example of the interface</A> (access may
have been denied).

<P><CENTER>
<TABLE CELLPADDING=0, CELLSPACING=0 BORDER=0>
<TR><TD ALIGN=left>
<IMG SRC="image.gif" BORDER=0 ALT="[graphic]" ALIGN=bottom>&nbsp;
<A HREF="update.gif" TARGET="_blank">UPDate Navigation Graphic</A>
<P>
<IMG SRC="image.gif" BORDER=0 ALT="[graphic]" ALIGN=bottom>&nbsp;
<A HREF="edit.gif" TARGET="_blank">UPDate Edit Graphic</A>
</TD></TR>
</TABLE>
</CENTER>
)

<COMMENT>(HTML/OFF)
<P> Consult the current <EMPHASIS>(Upd\BOLD)ate documentation for usage detail.
<P><BOX>(online hypertext link)
<P><BOX>(online graphic)
<P><BOX>(online graphic)
<COMMENT>(HTML/ON)

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

<HEAD>(Update Access Permission\head_web_update_permission)

<P> If SSL is in use (<REFERENCE>(chapter_ssl)) then username/password
privacy of the authorization environment is inherently secured via the
encrypted communications. To restrict web update functionality to this secure
environment add the following to the HTTPD$MAP configuration file:

<CODE_EXAMPLE>
  /upd/*  "403 Access denied."  ![sc:https]
<ENDCODE_EXAMPLE>

<P> Of course, the user must have write (POST/PUT) access to the document or
area on the server (i.e. the <EMPHASIS>(path)) and the server account have file
system permission to write into the <UNDERLINE>(parent directory).

<P> The server will report <QUOTE>(Insufficient privilege or object protection
violation ... /path/document) if it does not have file system permission to
write into a directory.

<P> Also see <REFERENCE>(head_auth_control_acls) for information on write
access control for the server account.

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

<CHAPTER>(Utilities and Facilities\chapter_utilities)

<P> Foreign commands for external utilities (and the HTTPD control
functionality) will need to be assigned from the adminstration users' LOGIN.COM
either explicitly or by calling the

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

<COMMENT>(HTML=
<A HREF="/ht_root/example/wasdverbs.com">HT_ROOT:[EXAMPLE]WASDVERBS.COM</A>
)

<COMMENT>(HTML/OFF)
HT_ROOT:[EXAMPLE]WASDVERBS.COM
<COMMENT>(HTML/ON)

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

procedure.

<CODE_EXAMPLE>
  $ AB == "$HT_EXE:AB"
  $ HTTPD == "$HT_EXE:HTTPD"
  $ HTTPDMON == "$HT_EXE:HTTPDMON"
  $ MD5DIGEST == "$HT_EXE:MD5DIGEST"
  $ QDLOGSTATS == "$HT_EXE:QDLOGSTATS"
  $ SECHAN == "$HT_EXE:SECHAN"
  $ STREAMLF == "@HT_EXE:STREAMLF"
  $ WB == "$HT_EXE:WB"
<ENDCODE_EXAMPLE>

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

<HEAD1>(Echo Facility\head_echo)

<P> Ever had to go to extraordinary lengths to find out exactly what your
browser is sending to the server? The server provides a request echo facility.
This merely returns the complete request as a plain-text document. This can be
used for for checking the request header lines being provided by the browser,
and can be valuable in the diagnosis of POSTed forms, etc.

<P> This facility must be enabled through a mapping rule entry.

<CODE_EXAMPLE>
  script /echo/* /echo/*
<ENDCODE_EXAMPLE>

<P> It may then be used with any request merely by inserting <QUOTE>(/echo) at
the start of the path, as in the following example.

<CODE_EXAMPLE>
  http://wasd.dsto.defence.gov.au/echo/ht_root/
<ENDCODE_EXAMPLE>

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

<HEAD1>(Hiss Facility\head_hiss)

<P> The <EMPHASIS>(hiss) facility provides a response stream made up of random
alpha-numeric characters (a sort of alpha-numeric white-noise).  No response
header is generated and the stream will continue (by default) up to one
megabyte of output, or until the client closes the connection.

<P> This facility must be enabled through a mapping rule entry.

<CODE_EXAMPLE>
  script /hiss/* /hiss/*
<ENDCODE_EXAMPLE>

<P> Usage details are described in <REFERENCE>(head_config_attacks).

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

<HEAD1>(Where Facility\head_where)

<P> Need to locate where VMS has the HTTPd files?  This simple facility maps
the supplied path then parses it to obtain a resulting VMS file specification.
<EMPHASIS>(This does not demonstrate whether the path actually exists!\BOLD)

<P> This facility must be enabled through a mapping rule entry.

<CODE_EXAMPLE>
  script /where/* /where/*
<ENDCODE_EXAMPLE>

<P> It may then be used with any request merely by inserting <QUOTE>(/where) at
the start of the path, as in the following example.

<CODE_EXAMPLE>
  http://wasd.dsto.defence.gov.au/where/ht_root/
<ENDCODE_EXAMPLE>

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

<HEAD1>(Xray Facility\head_xray)

<P> The Xray facility returns a request's complete response, <EMPHASIS>(both
header and body\BOLD), as a plain text document.  Being able to <EMPHASIS>(see)
the internals of the response header as well as the contents of the body
rendered in plain text can often be valuable when developing scripts, etc.

<P> This facility must be enabled through a mapping rule entry.

<CODE_EXAMPLE>
  script /Xray/* /Xray/*
<ENDCODE_EXAMPLE>

<P> It may then be used with any request merely by inserting <QUOTE>(/xray) at
the start of the path, as in the following example.

<CODE_EXAMPLE>
  http://wasd.dsto.defence.gov.au/xray/ht_root/
<ENDCODE_EXAMPLE>

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

<HEAD1>(Apache Bench\head_apache_bench)

<P> This server stress-test and benchmarking tool, as used in the Apache
Distribution, is included with the WASD package (sourced from
http://webperf.zeus.co.uk/ab.c), within

<COMMENT>(HTML=<A HREF="/ht_root/doc/misc/apache_group_licence.txt">license</A>)

<COMMENT>(HTML/OFF)
license
<COMMENT>(HTML/ON)

conditions.

<CODE_EXAMPLE>
  Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd.
  Copyright (c) 1998 The Apache Group.
<ENDCODE_EXAMPLE>

<P> <EMPHASIS>(Apache Bench will only compile and run for Alpha, IA64 or VAX
systems with VMS 7.<EMPHASIS>(n) or greater available.\BOLD) Also see the WASD
analogue, <REFERENCE>(head_wasd_bench). Apache Bench is a simple but effective
tool, allowing a single resource to be requested from a server a specified
number of times and with a specified concurrency.  This can be used to
benchmark a server or servers, or be used to stress-test a server
configuration's handling of variable loads of specific resquests (before
exhausting process quotas, etc.)

<P> A small addition to functionality has been made.  The WASD Apache Bench
displays a count of the HTTP response categories received (i.e. the number of
2<EMPHASIS>(nn)s, 4<EMPHASIS>(nn)s, etc.)  This allows easier assessment of
the relevance of results (i.e. measuring performance of some aspect only to
find the results showed the performance of 404 message generation - and yes, an
annoying experience of the author's prompted the changes!)

<P>The following examples illustrate it's use.

<CODE_EXAMPLE>
  $ AB -H
  $ AB -C 10 -N 100 http://the.server.name/ht_root/exercise/0k.txt
  $ AB -C 50 -N 500 -K http://the.server.name/ht_root/exercise/64k.txt
  $ AB -C 10 -N 100 http://the.server.name/cgi-bin/cgi_symbols
<ENDCODE_EXAMPLE>

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

<HEAD1>(CALogs\head_calogs)

<P> The Consolidate Access LOGS utility (pronounced similar to the breakfast
cereal brand :^) merges multiple HTTP server common and combined format access
logs into a single log file with records in time-order.  Due to the granularity
of HTTP server entry timestamps (one second) the records are sorted to the one
second but not within the one second.

<P> It uses RMS and the VMS sort-merge routines to provide it's basic
consolidation functionality.  An RMS search uses the supplied wildcard log file
specification.  Matching files are opened and each record read.  The date/time
field is parsed and a binary timestamp generated.  Records with formats or
date/time fields that do not make sense to the utility are discarded.  When all
files have been   processed the sort-merge is  performed using the timestamp as
the key.  The sorted records are then written to the specified output file.

<P> <EMPHASIS>($ calogs <LITERAL>(<log-file-spec> [<output-file-name>] [<qualifiers>])\BOLD)

<LIST>(SIMPLE)

<LE> <EMPHASIS>(/HELP\BOLD) basic usage information
<LE> <EMPHASIS>(/NOPROXY\BOLD) discard proxy service records
<LE> <EMPHASIS>(/NOWASD\BOLD) discard WASD server status/timestamp entries
<LE> <EMPHASIS>(/OUTPUT=\BOLD) alternate method of specifying merged file name
<LE> <EMPHASIS>(/PROXY\BOLD) discard non-proxy service records
<LE> <EMPHASIS>(/QUIET\BOLD) no messages apart from errors
<LE> <EMPHASIS>(/VERBOSE\BOLD) per-file progress messages
<LE> <EMPHASIS>(/VERSION\BOLD) display the utility version and copyright message

<ENDLIST>

<HEAD>(Usage Examples\head_calogs_examples)

<CODE_EXAMPLE>
  $ CALOGS == "$HT_EXE:CALOGS"
  $ CALOGS HT_LOGS:*200205*.LOG 2002_MAY.LOG
  $ CALOGS /VERBOSE HT_LOGS:
  $ CALOGS /NOWASD HT_LOGS:*200206*.LOG_* /OUTPUT=2002_JUNE.LOG
  $ CALOGS /PROXY /NOWASD HT_LOGS:*2002*.LOG 2002_PROXY.LOG
<ENDCODE_EXAMPLE>

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

<HEAD1>(HTAdmin\head_htadmin)

<P> The HTAdmin utility assists in with the command-line maintenance of $HTA
authorization databases (see <REFERENCE>(head_auth_quick_other) and
<REFERENCE>(head_auth_sources)).

<P> <EMPHASIS>($ htadmin <LITERAL>(<database> [<username>] [<qualifiers>])\BOLD)

<LIST>(SIMPLE)

<LE> <EMPHASIS>(/ADD\BOLD) add a new record
<LE> <EMPHASIS>(/CONFIRM\BOLD) confirm deletion of database
<LE> <EMPHASIS>(/CONTACT=<LITERAL>("<string>")\BOLD) contact information for record
<LE> <EMPHASIS>(/CREATE\BOLD) create a new database
<LE> <EMPHASIS>(/CSV[=TAB<VBAR>char]\BOLD) comma-separated listing (optional character)
<LE> <EMPHASIS>(/DATABASE=\BOLD) database name (or as command-line parameter)
<LE> <EMPHASIS>(/DELETE\BOLD) delete a database or username record from a database
<LE> <EMPHASIS>(/DISABLED\BOLD) username record is disabled (cannot be used)
<LE> <EMPHASIS>(/EMAIL=<LITERAL>("<string>")\BOLD) email address for record
<LE> <EMPHASIS>(/ENABLED\BOLD) username record is enabled (can be used)
<LE> <EMPHASIS>(/FULL\BOLD) listing showing full details
<LE> <EMPHASIS>(/GENERATE\BOLD) generate a six character password
<LE> <EMPHASIS>(/HELP\BOLD) basic usage information
<LE> <EMPHASIS>(/[NO]HTTPS\BOLD) synonym for /SSL
<LE> <EMPHASIS>(/LIST\BOLD) listing (brief by default, see /FULL and /CSV)
<LE> <EMPHASIS>(/MODIFY\BOLD) synonym for /UPDATE
<LE> <EMPHASIS>(/NAME=<LITERAL>("<string>")\BOLD) full name for username record
<LE> <EMPHASIS>(/OUTPUT=\BOLD) alternate output for database listing
<LE> <EMPHASIS>(/PASSWORD[=<LITERAL>(<string>)]\BOLD) username record password (prompts if not supplied)
<LE> <EMPHASIS>(/PIN\BOLD) generate four-digit "PIN number" for password
<LE> <EMPHASIS>(/[NO]READ\BOLD) username can/can't read
<LE> <EMPHASIS>(/SORT[=<LITERAL>(<parameters>)]\BOLD) sort the records into a new/another database
<LE> <EMPHASIS>(/[NO]SSL\BOLD) user can only authenticate via SSL (<QUOTE>(https:))
<LE> <EMPHASIS>(/[NO]WRITE\BOLD) username can/can't write
<LE> <EMPHASIS>(/UPDATE\BOLD) update an existing username record
<LE> <EMPHASIS>(/USER=<LITERAL>(<string>)\BOLD) username
<LE> <EMPHASIS>(/VERSION\BOLD) display version of HTADMIN
<ENDLIST>

<HEAD>(Usage Examples\head_htadmin_examples)

<LIST>(UNNUMBERED)

<LE> To create a new database named EXAMPLE.$HTA (in the current directory)

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE /CREATE
<ENDCODE_EXAMPLE>

<LE> Delete an existing database

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE /DELETE /CONFIRM
<ENDCODE_EXAMPLE>

<LE> List (briefly) the records

<CODE_EXAMPLE>
<ENDCODE_EXAMPLE>
   $ HTADMIN EXAMPLE

<LE> List (briefly) the specific user record DANIEL

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE DANIEL
<ENDCODE_EXAMPLE>

<LE> List all detail (132 colums) of the specified user record

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE DANIEL /FULL
<ENDCODE_EXAMPLE>

<LE> To add the new record DANIEL with default read access

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE DANIEL /ADD /NAME="Mark Daniel" 
<ENDCODE_EXAMPLE>

<LE> Add the new record DANIEL with contact details and read+write access

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE DANIEL /ADD /WRITE /CONTACT="Postal Address"
<ENDCODE_EXAMPLE>

<LE> Add the new record DANIEL and be prompted for a password, or to specify the
password on the command-line, or have the utility generate a password or
four-digit PIN style password (which is displayed after the record is
sucessfully added)

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE DANIEL /ADD /NAME="Mark Daniel" /PASSWORD
   $ HTADMIN EXAMPLE DANIEL /ADD /NAME="Mark Daniel" /PASSWORD=cher10s
   $ HTADMIN EXAMPLE DANIEL /ADD /NAME="Mark Daniel" /GENERATE
   $ HTADMIN EXAMPLE DANIEL /ADD /NAME="Mark Daniel" /PIN
<ENDCODE_EXAMPLE>

<LE> To update an existing record

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE DANIEL /UPDATE /EMAIL="Mark.Daniel@wasd.vsm.com.au"
<ENDCODE_EXAMPLE>

<LE> Update the specified record's password (interactively) then to generate a four
digit PIN for a password (which is then displayed)

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE DANIEL /UPDATE /PASSWORD
   $ HTADMIN EXAMPLE DANIEL /UPDATE /GENERATE
   $ HTADMIN EXAMPLE DANIEL /UPDATE /PIN
<ENDCODE_EXAMPLE>

<LE> Disable then enable an existing user record without changing anything else

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE DANIEL /UPDATE /DISABLE
   $ HTADMIN EXAMPLE DANIEL /UPDATE /ENABLE
<ENDCODE_EXAMPLE>

<LE> To list the entire database, first briefly, then in 132 column mode (with all
detail), then finally as a comma-separated listing

<CODE_EXAMPLE>
   $ HTADMIN EXAMPLE
   $ HTADMIN EXAMPLE /FULL
   $ HTADMIN EXAMPLE /CSV
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(Sort Details\head_htadmin_sort)

<P> The /SORT qualifier sorts the current database records according to the
/SORT= parameters.  It can be used with the /LIST qualifier to produce ordered
reports or will output the records into another authentication file.  By
default it sorts ascending by username.  Qualifier parameters allow a sort by
DATE or COUNT.  Each of these allows the further specification of which date or
count; ACCESS, CHANGE or FAILURE.

<LIST>(UNNUMBERED)

<LE> Generating a listing with specified order

<CODE_EXAMPLE>
  $ HTADMIN EXAMPLE /LIST /SORT=DATE=ACCESS
  $ HTADMIN EXAMPLE /LIST /SORT=COUNT=FAILURE /OUTPUT=EXAMPLE.LIS
<ENDCODE_EXAMPLE>

<LE> Sort descending by username into a higher version of EXAMPLE.$HTA

<CODE_EXAMPLE>
  $ HTADMIN EXAMPLE /SORT
<ENDCODE_EXAMPLE>

<LE> To sort by username into another .$HTA file

<CODE_EXAMPLE>
  $ HTADMIN EXAMPLE /SORT /OUTPUT=ANOTHER
<ENDCODE_EXAMPLE>

<LE> List by most-recently accessed

<CODE_EXAMPLE>
  $ HTADMIN EXAMPLE /LIST /SORT=DATE
<ENDCODE_EXAMPLE>

<LE> List by most-recently failed to authenticate

<CODE_EXAMPLE>
  $ HTADMIN EXAMPLE /LIST /SORT=DATE=FAILURE
<ENDCODE_EXAMPLE>

<LE> Sort file into order by most frequently authenticated (accessed)

<CODE_EXAMPLE>
  $ HTADMIN EXAMPLE /SORT=COUNT
<ENDCODE_EXAMPLE>

<ENDLIST>

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

<HEAD1>(HTTPd Monitor\head_httpdmon)

<P> The HTTP server may be monitored in real-time using the HTTPDMON utility.

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

<COMMENT>(HTML=
<P><CENTER>
<IMG SRC="image.gif" BORDER=0 ALT="[graphic]" ALIGN=bottom>&nbsp;
<A HREF="httpdmon.gif" TARGET="_blank">HTTPDMON Graphic</A>
</CENTER>
)

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

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

<P> This utility continuously displays a screen of information comprising three
or four of the following sections: 

<LIST>(NUMBERED)

<LE> <EMPHASIS>(Process Information\BOLD)
<LINE>
HTTPd process information includes its up-time, CPU-time consumed (excluding 
any subprocesses), I/O counts, and memory utilization.  The <QUOTE>(Servers:)
item shows how many servers are currently running on the node/cluster.  Changes
in this count are indicated by the second, parenthesized number.

<LE> <EMPHASIS>(General Server Counters\BOLD)
<LINE>
The server counters keep track of the total connections received, accepted, 
rejected, etc., totals for each request type (file transfer, directory 
listing, image mapping, etc.).

<LE> <EMPHASIS>(Proxy Serving Counters\BOLD)
<LINE>
The server counters keep track of proxy serving connections, network and cache
traffic, cache status, etc.

<LE> <EMPHASIS>(Latest Request\BOLD)
<LINE>
This section provides the response status code, and some transaction
statistics, the service being accessed, originating host and HTTP request. 
Note that long request strings may be truncated (indicated by a bolded
elipsis).

<LE> <EMPHASIS>(Status Message\BOLD)
<LINE>
If the server is in an exceptional condition, for example exited after a fatal
error, starting up, etc., a textual message may be displayed in place of the
the request information.  This may be used to initiate remedial actions, etc.

<ENDLIST>

<P> The following shows example output (after WWWRKOUT server testing):

<PAGE>
<CODE_EXAMPLE>
   WASD:: 1         HTTPDMON v2.0.0 AXP        Saturday, 12-MAY-2001 11:26:18

 Process: HTTPd:80  PID: 2020022F  User: HTTP$SERVER  Version: 7.2
      Up: 0 21:05:51.88  CPU: 0 07:34:19.99  Startup: 1
 Pg.Flts: 3526  Pg.Used: 37%  WsSize: 6402  WsPeak: 4729
     AST:  196/200   BIO: 1003/1020  BYT: 202270/202720  DIO: 498/500
     ENQ: 1989/2000  FIL:  298/300   PRC:    100/100      TQ:  26/30

 Request: 184865  Current:16  Throttle: 0/0/0%  Peak: 29
  Accept: 178212  Reject:0  Busy:0  SSL: 17 
 CONNECT: 0  GET: 164717  HEAD: 20148  POST: 0  PUT: 0
   Admin: 0  Cache: 48/39992/0  DECnet: 3327/6655  Dir: 6670
     DCL: CLI:16730 CGI:9987 CGIplus:13310/13182 RTE:16/15 Processes: 168/5
    File: 3384/0  IsMap: 0  Proxy: 64911  Put: 0  SSI: 16657  Upd: 9988

     1xx: 0  2xx: 157816  3xx: 3  4xx: 18496 (403:27)  5xx: 1864  (none:0)
      Rx: 19,762,345  Tx: 1,053,847,437  (bytes)

   Proxy: enabled
 CONNECT: 0  GET: 58720  HEAD: 6191  POST: 0  PUT: 0
     Not: Cacheable Request:14555 Response:23786
 Network: Rx:118,463,055 Tx:7,208,716 (29%)  Accessed: 38356
  Lookup: Numeric:19 DNS:21 Cache:38317 Error:1
   Cache: Rx:2,863,617 Tx:320,164,012 (71%)  Read:26554/3 Write:10
  Device: DKA0: 4110480 blocks (2007MB)  Space: available
          2171744 used (1060MB 53%), 1938736 free (946MB 47%)
   Purge: 18 00:00:54, 98 files (2254/2412), 0 deleted (0/0)

    Time: 12 11:25:11  Status: 200  Rx: 95  Tx: 34479  Duration: 0.2400
 Service: beta.dsto.defence.gov.au:80  
    Host: beta.dsto.defence.gov.au (131.185.250.201)
 Request: GET /ht_root/exercise/64k.txt
<ENDCODE_EXAMPLE>

<P> The <QUOTE>(/HELP) qualifier provides a brief usage summary.

<P> The server counter values are carried over when a server (re)starts 
(provided the system has stayed up).  To reset the counters use the online
Server Administration facility (<REFERENCE>(chapter_server_admin)).

<P> If [DNSlookup] is disabled for the HTTP server the HTTPDMON utility
attempts to resolve the literal address into a host name. This may be disabled
using the /NORESOLVE qualifier.

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

<HEAD1>(MD5digest\head_md5digest)

<P> From RFC1321 <HELLIPSIS>

<P> <QUOTE>( The [MD5] algorithm takes as input a message of arbitrary length
and produces as output a  128-bit "fingerprint" or "message digest" of the
input. It is conjectured that it is computationally infeasible to produce two
messages having the same message digest, or to produce any message having a
given prespecified target message digest. )

<P> The MD5DIGEST utility is primarily provided with WASD for verifying kits
as unchanged from the originals released.  With the proliferation of mirror
sites and other distribution resources it has become good practice to ensure
kits remain unchanged from release, to distribution, to installation site
(changes due to to data corruption or malicious intent - as remote a
possibility as that may seem).  Of course it may also be used for any other
purpose where the MD5 hash is useful.

<P> For verifying the contents of a WASD release connect to the
<EMPHASIS>(original\BOLD) WASD distribution site, refer to the download page,
and make a comparison between the release MD5 hash found against the list of
all archive hashes and the MD5 hash of your archive.  That can be done as
follows

<CODE_EXAMPLE>
  $ MD5DIGEST == "$HT_EXE:MD5DIGEST"
  $ MD5DIGEST device:[dir]archive.ZIP
<ENDCODE_EXAMPLE>

<CP> The result will look similar to

<CODE_EXAMPLE>
  MD5 (kits:[000000]htroot710.zip;1) = 404bbdfe0f847c597b034feef2d13d2d
<ENDCODE_EXAMPLE>

<P> Of course, if you have not yet installed your first WASD distribution using
the MD5DIGEST utility that is part of it is not feasable.  The original site
can provide kits and pre-built executables for this purpose.

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

<HEAD1>(QDLogStats\head_qdlogstats)

<P> <EMPHASIS>(Quick-and-Dirty LOG STATisticS\BOLD) is a utility to extract
very elementary statistics from Web server common/combined format log files. 
It is intended for those moments when we think <QUOTE>(I wonder how many times
that new archive has been downloaded?), <QUOTE>(How much data was transfered
during November?), <QUOTE>(How often is <EMPHASIS>(such-and-such) a client
using the authenticated <EMPHASIS>(so-and-so) service?), <QUOTE>(How much has
the mail service been used?) <HELLIPSIS> and want the results in a matter of
seconds (or at least a few tens of seconds ;^)   It is available at the
command-line and as a CGI script.

<P> For QDLOGSTATS to be available as a CGI script it <EMPHASIS>(must\BOLD)
have authorization enabled against it (to prevent potential ad hoc browsing of
a site's logs).  The following provides some indication of this configuration,
although of course it requires tailoring for any given site.

<CODE_EXAMPLE>
  [VMS]
  /cgi-bin/qdlogstats ~webadmin,131.185.250.*,r+w ;
<ENDCODE_EXAMPLE>

<P> It could then be accessed using

<CODE_EXAMPLE>
  http://the.host.name/cgi-bin/qdlogstats
<ENDCODE_EXAMPLE>

<P> The initial access provides a form allowing the various filters and other
behaviours to be selected.  The CGI form basically parallels the command-line
behaviour described below.

<HEAD>(Filters\head_qdlogstats_filters)

<P> A number of filters allow subsets of the log contents to be selected. 
These filters support the same string matching expressions as the server
(<REFERENCE>(chapter_string_matching)).

<P> A knowlege of the format and contents of the <EMPHASIS>(common) and
<EMPHASIS>(combined) log formats will assist in deciding which and to what
purpose filters should be used.  Record filtering is done in the same order as
is finally displayed, so <EMPHASIS>(method) would be processed before
<EMPHASIS>(user-agent) for instance.  Normally a record match terminates on the
first non-matched filter (to expedite processing).  To compare and report each
filter for every record apply the /ALL qualifier.  To view records as they are
processed use the /VIEW qualifier.  This by default displays all matched
records, but the optional =ALL or =NOMATCH parameters will display all records, 
or all those but the matches.

<P> <EMPHASIS>($ QDLOGSTATS <LITERAL>(log-file-spec [pattern qualifiers]
[other qualifiers])\BOLD)

<LIST>(SIMPLE)

<LE> <EMPHASIS>(/ALL\BOLD) compare and report on all supplied filters
<LE> <EMPHASIS>(/AUTHUSER=\BOLD) pattern (any authenticated username) 
<LE> <EMPHASIS>(/BEFORE=\BOLD) log files before this VMS date/time  
<LE> <EMPHASIS>(/CLIENT=\BOLD) pattern (client host name or IP address)  
<LE> <EMPHASIS>(/DATETIME=\BOLD) pattern (<QUOTE>(11/Jun/1999:14:08:49 +0930))
<LE> <EMPHASIS>(/DECODE[=<EMPHASIS>(<LITERAL>(keyword))]\BOLD)
URL-decode PATH, QUERY, REFERER before match
<LE> <EMPHASIS>(/METHOD=\BOLD) pattern (HTTP <QUOTE>(GET), <QUOTE>(POST), etc.)  
<LE> <EMPHASIS>(/OUTPUT=\BOLD) file specification 
<LE> <EMPHASIS>(/PATH=\BOLD) pattern (URL path component only) 
<LE> <EMPHASIS>(/PROGRESS\BOLD) show progress during processing
<LINE> (a <QUOTE>(+) for each file started, a <QUOTE>(.) for each 1000 records
processed)
<LE> <EMPHASIS>(/QUERY=\BOLD) pattern (URL query component only) 
<LE> <EMPHASIS>(/REFERER=\BOLD) pattern (HTTP <QUOTE>(Referer:) field, COMBINED
only)
<LE> <EMPHASIS>(/REMOTEID=\BOLD) pattern (RFC819 file) 
<LE> <EMPHASIS>(/RESPONSE=\BOLD) pattern (HTTP response code) 
<LE> <EMPHASIS>(/SINCE=\BOLD) log files after this VMS date/time  
<LE> <EMPHASIS>(/SIZE[=<EMPHASIS>(<LITERAL>(keyword))]\BOLD)
response size (in bytes) MIN=<EMPHASIS>(<LITERAL>(integer))
MAX=<EMPHASIS>(<LITERAL>(integer))
<LE> <EMPHASIS>(/USERAGENT=\BOLD) pattern (HTTP <QUOTE>(User-Agent:) field,
COMBINED only) 
<LE> <EMPHASIS>(/VIEW[=type]\BOLD) display matching log records (ALL, NOMATCH,
MATCH)

<ENDLIST>

<HEAD>(Usage Examples\head_qdlogstats_examples)

<LIST>(UNNUMBERED)

<LE> Records from September 1999.

<CODE_EXAMPLE>
  $ QDLOGSTATS HT_LOGS:*1999*.LOG /DATE="*/SEP/1999*"
<ENDCODE_EXAMPLE>

<LE> Records where the browser was an X-based Netscape Navigator

<CODE_EXAMPLE>
    $ QDLOGSTATS HT_LOGS:*.LOG /USERAGENT=*MOZILLA*X11*
<ENDCODE_EXAMPLE>

<LE> Records of POST method requests

<CODE_EXAMPLE>
    $ QDLOGSTATS HT_LOGS:*.LOG /METHOD=POST
<ENDCODE_EXAMPLE>

<LE> Records requesting a particular path

<CODE_EXAMPLE>
    $ QDLOGSTATS HT_LOGS:*.LOG /PATH="/cgi-bin/*"
<ENDCODE_EXAMPLE>

<LE> Select proxy records requesting (a) particular site(s)

<CODE_EXAMPLE>
    $ QDLOGSTATS HT_LOGS:*8080*.LOG /PATH="http://*.compaq.com*"
    $ QDLOGSTATS HT_LOGS:*8080*.LOG /METHOD=POST /PATH="http://*sex*.*/*" /VIEW
<ENDCODE_EXAMPLE>

<LE> Records where the request was authenticated

<CODE_EXAMPLE>
    $ QDLOGSTATS HT_LOGS:*.LOG /AUTHUSER=DANIEL
<ENDCODE_EXAMPLE>

<ENDLIST>

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

<HEAD1>(SECHAN Utility\head_sechan)

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

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

<HEAD1>(Scrunch Utility <EMPHASIS>((obsolete))\head_scrunch)

<NOTE>(SCRUNCH Obsolete with 7.2)
Changes with server-internal SSI document handling have made the SCRUNCH
utility obsolete for WASD versions 7.2 and later.  Previously SCRUNCHed
documents will continue to be processed without needing to be explicitly
UNSCRUNCHed.
<ENDNOTE>

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

<HEAD1>(StreamLF Utility\head_streamlf)

<P> This simple procedure used the FDL facility to convert files to STREAM_LF
format. The WASD HTTPd  server access STREAM_LF files in block/IO-mode, far
more efficiently that the record-mode required by variable-record format files.

<P> <EMPHASIS>(NOTE: \BOLD) The server can also be configured to automatically
convert any VARIABLE record format files it encounters to STREAM_LF.

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

<HEAD1>(WASD Bench :^<CPAREN>\head_wasd_bench)

<P> WASD Bench - an analogue to Apache Bench (<REFERENCE>(head_apache_bench))
Why have it?  Apache Bench only compiles and runs on VMS 7.n and later.  This
version should compile and run for all supported WASD configurations.  It also
has the significant performance advantage (looks like ~25%) of using the
underlying $QIO services and not the socket API, and is AST event driven rather
than using the likes of select().  It is not a full implementation of AB (for
instance, it currently does not do POSTs).  The CLI attempts to allow the same
syntax as used by AB (within the constraint that not all options are supported)
so that it is relatively easy to switch between the two (perhaps for comparison
purposes) if desired.

<P>The following examples illustrate it's use.

<CODE_EXAMPLE>
  $ WB -H
  $ WB -C 10 -N 100 http://the.server.name/ht_root/exercise/0k.txt
  $ WB -C 50 -N 500 -K http://the.server.name/ht_root/exercise/64k.txt
  $ WB -C 10 -N 100 http://the.server.name/cgi-bin/cgi_symbols
<ENDCODE_EXAMPLE>

<P> WASD Bench also has an <EMPHASIS>(exercise) option, functionality is not
found in Apache Bench.  It is basically to supercede  similar functionality
provided by the retired WWWRKOUT.  The exercise functionality allows WASD Bench
to be used to stress-test a server.  This behaviour includes mixing HEAD (~5%)
with GET requests, and breaking requests during both request and response
transfers (~5%).  These are designed to shake up the server with indeterminate
request types and client error behaviours.  The best way to utilize this
stress-testing is wrap WASD Bench with a DCL procedure providing a variety of
different requests types, quantities and concurrencies.

<CODE_EXAMPLE>
  $!(example "wrapper" procedure)
  $ IF P1 .EQS. "" THEN P1 = F$GETSYI("NODENAME")
  $ WB = "$HT_EXE:WB"
  $ SPAWN/NOWAIT WB +e +s +n -n 100 -c  5    http://'p1'/ht_root/exercise/0k.txt
  $ SPAWN/NOWAIT WB +e +s -k -n  50 -c  5 -k http://'p1'/ht_root/exercise/64k.txt
  $ SPAWN/NOWAIT WB +e +s    -n  50 -c  2    http://'p1'/cgi-bin/conan
  $!(delay spawning anymore until this one concludes)
  $              WB +e +s    -n 100 -c  5    http://'p1'/ht_root/*.*
  $ SPAWN/NOWAIT WB +e +s +n -n 100 -c  1    http://'p1'/ht_root/exercise/16k.txt
  $ SPAWN/NOWAIT WB +e +s    -n  10 -c  1    http://'p1'/cgi-bin/doesnt-exist
  $ SPAWN/NOWAIT WB +e +s -k -n  50 -c  2    http://'p1'/cgi-bin/conan/search
  $!(delay spawning anymore until this one concludes)
  $              WB +e +s    -n  50 -c  2    http://'p1'/ht_root/src/httpd/*.*
  $!(etc.)
<ENDCODE_EXAMPLE>

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

<HEAD1>(Server Workout <EMPHASIS>((obsolete))\head_wwwrkout)

<NOTE>(WWWRKOUT Obsolete with 8.0)
As the WASD Bench :^) Utility now provides much of the <EMPHASIS>(stress-test)
functionality the WWWRKOUT utility supplied with earlier version of WASD has
been declared obsolete.
<ENDNOTE>

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