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

<CHAPTER>(Server Administration\chapter_server_admin)

<P> All server configuration files, with the execption of the authentication
databases, are plain text and may be modified with any prefered editor. 
However the majority of these can also be administered on-line through a
browser.

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

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

<P> In addition a <A HREF="/upd/ht_root/">Web <B>Upd</B>ate facility</A> allows
some administration of file system portions of the Web.
)

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

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

<COMMENT>(HTML/OFF)
<P> A menu of server administration functions is provided by the server.
<P><BOX>(online hypertext link)

<P> In addition a Web <EMPHASIS>(Upd\BOLD)ate facility allows some
administration of file system portions of the Web.
<COMMENT>(HTML/ON)

See <REFERENCE>(chapter_web_update).

<HEAD1>(Authorization\head_admin_authorization)

<P> The section <REFERENCE>(head_auth_quick_identifier) provides a quick guide
to setting up authorization for server administration purposes.

<P> It is also recommended that for production sites the path to these reports
be controlled via authentication and authorization, using both host and
username restrictions, similar to the following:

<CODE_EXAMPLE>
  [WHATEVER-REALM]
  /httpd/-/admin/*  host.ip.addr,~WebMaster,~WhoEverElse,r+w
<ENDCODE_EXAMPLE>

<P> If a full authorization environment is not required but
administration via browser is still desired restrict access to browsers
executing on the server system itself, using an appropriate
SYSUAF-authenticated username. Provision of a VMS account for server
administration only is quite feasable, see
<REFERENCE>(head_auth_web_only).

<CODE_EXAMPLE>
  [VMS]
  /httpd/-/admin/*  #localhost,~<EMPHASIS>(username),r+w
<ENDCODE_EXAMPLE>

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

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

<P> When using the <EMPHASIS>(revise) capability of the administration menu it
is necessary to comply with all the requirements for Web update of files.
This is discussed in general terms in <REFERENCE>(chapter_web_update).
Revision of server configuration files requires path permissions allowing
write access for the username(s) doing the administration, as well as the
required ACL on the target directory (in the following example
HT_ROOT:[LOCAL]).

<CODE_EXAMPLE>
  [VMS]
  /httpd/-/admin/*  #localhost,~<EMPHASIS>(username),r+w
  /ht_root/local/*  #localhost,~<EMPHASIS>(username),r+w
<ENDCODE_EXAMPLE>

<P> It is possible to allow general access to the administration menu and
reports while restricting the ability to initiate server actions such as a
restart! Using the WORLD realm against the path is necessary, for the obvious
security reason, the server administration module will not allow itself to be
used without an authenticated username, provided as a pseudo-authenticated
<QUOTE>(WORLD).

<CODE_EXAMPLE>
  [VMS]
  /httpd/-/admin/control/*  #localhost,~<EMPHASIS>(username),r+w
  [WORLD]
  /httpd/-/admin/* r
<ENDCODE_EXAMPLE>

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

<HEAD1>(Breaking-in To The Server!\head_admin_breakin)

<P> The server's authentication/authorization environment can be circumvented
under special circumstances.  <EMPHASIS>(Note that this is not possible without
administrator action and persists only as long as the administrator actually
performs the action!\BOLD)

<P> This provision exists for only four foreseeable situations:

<LIST>(NUMBERED)

<LE> ad hoc server configuration

<LE> initial configuration of the authentication environment

<LE> loss of the administrator's password

<LE> demonstration/experimentation purposes

<ENDLIST>

<HEAD>(Method\head_admin_breakin_method)

<P> If performing the initial authentication configuration
<COMMENT>(HTML/OFF)
<P>
<COMMENT>(HTML/ON)
<UNDERLINE>(<EMPHASIS>(make sure the HT_AUTH logical is correctly
defined\BOLD)) when planning to use HTA databases.

<P> Manually start a new instance of the server on a non-standard port using
the /PROMISCUOUS qualifier.  This can be done at the command line.  There is
now a security hole.  Example:

<CODE_EXAMPLE>
  $ HTTPD = "$HT_EXE:HTTPD.EXE"
  $ SPAWN /WAIT HTTPD /NOLOG /SERVICE=8088 /PROMISCUOUS
<ENDCODE_EXAMPLE>

<P> This server with then allow access using any username/password combination.
Even if not completely paranoid it's perhaps a good idea to append a specific
password to the qualifier, the server will then only authenticate to that.

<CODE_EXAMPLE>
  $ SPAWN /WAIT HTTPD /NOLOG /SERVICE=8088 /PROMISCUOUS=VERYCAUTIOUS
<ENDCODE_EXAMPLE>

<P> Access this instance of the server with a browser and use the server
administration menu.

<CODE_EXAMPLE>
  <COMMENT>(HTML=<A HREF="/httpd/-/admin/">http://host:port/httpd/-/admin/</A>)
<COMMENT>(HTML/OFF)
  http://host:port/httpd/-/admin/
<COMMENT>(HTML/ON)
<ENDCODE_EXAMPLE>

<P> It is now possible to review server-generated reports, check rule mappings,
create databases, enter username details, change the administrator's password
to something known, etc., etc. Shutdown that server again (ctrl-Y) and the
security hole disappears.

<P> Note that if a site authorization rule already maps the administration
menu path or configuration file path the server may report duplicate path
errors. This is due to the /PROMISCUOUS startup effectively introducing the
following two rules, ensuring the menu and configuration files can be accessed
regardless of anything already in or missing from the authorization file.

<CODE_EXAMPLE>
  [PROMISCUOUS]
  # access to the server administration menu
  /httpd/-/admin/* r+w
  # access to write into the "usual" location for configuration files
  /ht_root/local/* r+w
<ENDCODE_EXAMPLE>

<P> Other rules may be placed in the local configuration file for the
[PROMISCUOUS] realm specifically for use during this mode of access. They will
not apply during normal server operation.  Be sure they are placed before other
rules in the file.

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

<HEAD1>(HTTPd Server Reports\head_server_reports)

<P> The server provides a number of internally generated reports.

<P> It is possible to use this facility standalone, without configuring
authorization, see <REFERENCE>(head_admin_breakin).

<LIST>(NUMBERED)

<LE><EMPHASIS>(Statistics - \BOLD)

Server process up-time, CPU-time and other resources consumed, number of
connections processed, number of requests of each HTTP method, type of
processing involved (HTTPd module used), number of bytes processed, etc.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Configuration - \BOLD)

A tabular summary of the server's current configuration.  This is
a convenient method for viewing the information from the HTTPD$CONFIG file.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Services - \BOLD)

A tabular report listing the current services (virtual servers) and the
service-specific parameters.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Messages - \BOLD)

A tabular report of the server's current message database, multiple
languages shown if configured that way.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Mapping - \BOLD)

All loaded mapping rules and any cached USER rule paths.  A selector allows
rules applying only to one particular virtual server to be displayed.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Path Authorization - \BOLD)

If authorization is in use (see <REFERENCE>(chapter_authorization)) this
report lists the paths with associated authorization and access control.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(User Authentication - \BOLD)

List any users that have been authorized since the server was last
started, the realm authorized from, the group it applies to (if any), and what
the user's capabilities are (allowed HTTP methods). A time-stamp and counters
provide additional information.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Cache - \BOLD)

Allows monitoring of cache behaviour and performance, as well as the files
currently in the cache. For further information see
<REFERENCE>(chapter_cache).

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(DCL Scripting\BOLD)

<P> Provides some DCL, CGI and CGIplus scripting information.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE>  DCL module statistics (same information as displayed in the server
statistics report).  These are cumulative for the entire life of the system
(unless zeroed).

<COMMENT>(HTML=<P>)

<LE> Subprocess information shows how many actual subprocesses exist at the
time of the report, as indicated by the PID and bolded, non-zero liftime (in
minutes). The <EMPHASIS>(soft-limit) specifies how many CGIplus scripts are
allowed to continue existing before the least used is deleted and the
<EMPHASIS>(hard-limit) show how many subprocesses may actually exist at any
one time (the margin allows for subprocess deletion latency). A count of how
many times the CGIplus subprocesses have been explicitly purged (button
available on this report page). The <EMPHASIS>(life-time) of zombie processes
(in minutes, zero implying use of zombies is disabled) and the number that
have been purged due to expiry. CGIplus subprocess life-time (in minutes, zero
implying indefinite), the number purged due to life-time expiry and the number
of CGIplus subprocesses that the server has actually purged (deleted) to
maintain the soft-limit margin specified above.

<COMMENT>(HTML=<P>)

<LE> Each of the allocated subprocess data structures is listed.  There may
be zero up to hard-limit items listed here depending on demand for DCL
activities and the life of the server.  Items with a PID shown indicate an
actual subprocess existing.  This can be a zombie subprocess or a CGIplus
subprocess.  If no subprocess is indicated then the other information
represents the state the last time the item's associated subprocess completed.
Information includes the script (URL-style path) or DCL command, total count of
times the item has been used and the last time it was.  The zombie count
indicates the number of time the same subprocess finished a request and entered
the <EMPHASIS>(zombie) state.  The CGIplus column indicates it is/was a CGIplus
script and shows the total number of times that particular script has been/was
used.  If the subprocess is currently in use the client information show the
client host name.

<COMMENT>(HTML=<P>)

<LE> If any subprocesses are associated with any data structure a
<EMPHASIS>(purge) button is provided that forces all subprocesses to be
deleted.  This can be useful if a new script image is compiled and it is
required all scripts now use this.  If a script is currently processing a
request the subprocess deletion occurs when that processing is complete. The
purge button <EMPHASIS>(does not force\BOLD) a subprocess to delete, so a
second button <EMPHASIS>(forces\BOLD) all subprocesses to delete immediately. 
This can be used to forceably clear errant scripts, etc., but be warned script
processing is indiscrimately stopped!

<ENDLIST>

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(DECnet Scripting\BOLD)

<P> DECnet module information shows totals for DECnet scripting usage and the
DECnet connection list.

<P> This list will grow, up to the specified configuration maximum, as
conconurrent scripting demand occurs. Maintained connections are indicated by
the bolded, non-zero lifetime (in minutes). When this reaches zero the task is
disconnected. The current/last task for that connection is indicated, along
with the number of times the connection was reused and a total number of uses
for that list item.

<P> <EMPHASIS>(Purge) and <EMPHASIS>(force) buttons allow current links to be
broken after request completion or forcibly disconnected.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Memory - \BOLD)

Provides a report and does an integrity check on each of the Virtual
Memory (VM) zones employed by the WASD HTTPd.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Process - \BOLD)

Lists all processes on the current system owned by the server account. 
From this list a process can be selected to have a <QUOTE>(SHOW PROCESS /ALL)
performed on it, displayed on a report page.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Proxy - \BOLD)

If proxy serving is enabled a report providing statistics on the various
HTTP methods used, network and cache traffic, cache reads and writes, requests
not cachable, and host name lookup are provided.  This may used to help guage
the effectiveness of the cache.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Request\BOLD)

<P> Lists current requests (always shows at least your own connection
accessing this report :^) and if enabled by configuration a history list of
the most recent requests (enabled by the configuration parameter
[RequestHistory]).  Current requests numbers may selected for
<EMPHASIS>(one-shot) WATCH-processing reports from this page (see
<REFERENCE>(chapter_watch)).

<P> Another diagnostic tool is available from the same link, the
<EMPHASIS>(WATCH-peek Report).  Two <QUOTE>(double-dots) precede the request
number.  The first accesses the basic peek report, providing the contents
selected internal fields and data structures of the request.  This is
primarily intended as a problem investiagtion and development tool, and will be
of limited value without an understanding of server internals.  The second
<QUOTE>(double-dot) accesses the internals then begins a one-shot
WATCH-processing report. 

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(SSL - \BOLD)

The SSL report lists counts of the number of SSL transactions initiated
and completed, along with session cache statistics for the currently connected
SSL service. It also lists the ciphers available and current session
information.

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(Activity\BOLD)

<P> Provide a graphical <EMPHASIS>(snapshot) of server activity of a given
period.

<P> This is dynamic data, held in memory only, and so is current only from the
latest server startup. It is enabled by the configuration parameter
[ActivityDays]. The administration menu provides several, represented
as a period of hours before the present time. Number of requests and bytes sent
to the client are represented by a histogram with respective means for each
during the period by a line graph. A <EMPHASIS>(greyed) area indicates no data
available for that time (i.e. before the latest server startup, or in the
future).

<P> Activity data is accumulated on a per-minute basis. This is the maximum
granularity of any report. When reports are selected that can display less
than this one minute granularity (i.e. with periods greater than four hours)
the value shown is the <EMPHASIS>(peak\BOLD) of the number of minutes sampled
for display. This better represents the load on the server than would a mean
of those samples.

<P> For browsers recognised as capable (with v4.3 of the server these are
Netscape Navigator 3.0ff and Microsoft Internet Explorer 3.02ff) this report
is JavaScript-enabled, and if in focus the browser refreshes itself at an
interval appropriate to the reporting period.  If not in focus, the report is
automatically refreshed when the browser is brought back into focus.

<P> The graph is an image map, various regions of which allow the selection of
other reports with different periods or durations. This allows previous
periods to be examined at various levels of detail using the graph for
navigation. Various sections may have no mapping as appropriate to the current
report.

<P> The following example shows the layout for a four hour report. The upper
and lower sections have distinct functions. The middle 50% of the upper
section allows the same end time (most commonly the current hour) to be
examined over twice the current period, in this case it would be over eight
hours. The left 25% allows the previous fours hours to be viewed (if such data
exists), and for non-current reports the right 25% allows the next four hours
to be viewed. The lower half can be divided into sections representing hours
or days depending on the period of the current report. This allows that period
to be viewed in greater detail. For single hour reports this section, of
course, is not mapped.

<P> Remember that the URL of the mapped section will be displayed in the
status bar of the browser. As the URL contains time components it is not a
difficult task to decipher the URL displayed to see the exact time and period
being selected.

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

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

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<LE><EMPHASIS>(WATCH - \BOLD)

This report provides an online, real-time, in-browser-window view of request
processing on the <EMPHASIS>(running server\BOLD). See
<REFERENCE>(chapter_watch) for details.

<ENDLIST>

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

<COMMENT>(HTML=<P>)

<HEAD1>(HTTPd Server Revise\head_server_revise)

<P> The server provides a comprehensive configuration revision facility.

<COMMENT>(HTML=<P>)

<LIST>(NUMBERED)

<LE> <EMPHASIS>(Configuration - \BOLD)
A form-driven interface allows the current configuration of the server to be
altered on-line.  This configuration may then be saved to the on-disk file and
then the server could be restarted using the new parameters.  The source of the
current configuration can be either the server itself (from it's volatile,
in-memory parameters) or from the on-disk configuration file.  In addition it
is possible to directly edit and update the on-disk file.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Services - \BOLD)
A form-driven interface allows service (virtual server) configuration.
It is also possible to directly edit and update the on-disk file.  The server
must be restarted for service changes to take effect.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Messages - \BOLD)
A form-driven interface allows the the server messages to be modified.
It is also possible to directly edit and update the on-disk file.  The
server can then be restarted to use the modified database (see
<REFERENCE>(head_server_action)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Mapping - \BOLD)
No form-driven interface is currently available for changing the mapping rules. 
However it is possible to directly edit and update the on-disk file.  The
mapping rules could then be reloaded, changing the current server rules (see
<REFERENCE>(head_server_action)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Path Authorization - \BOLD)
No form-driven interface is currently available for changing the path
authorization configuration. However it is possible to directly edit and update
the on-disk file.  The path authorization directives could the be reloaded,
changing the current server authorization (see <REFERENCE>(head_server_action)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(User Authentication - \BOLD)
User authentication comprises a number of dialogues that allow the
WASD-specific (HTA) authentication databases to be administered.  These
include:

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)
<LE> creating databases
<LE> deleting databases
<LE> accessing databases for administering usernames
<LE> listing usernames within databases
<LE> adding usernames
<LE> deleting usernames
<LE> modifying username permissions and other data
<LE> reseting in-server (cached) authentication information
<ENDLIST>

<P> Chapter <REFERENCE>(chapter_authorization) covers authentication detail.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Site Log - \BOLD)
This accesses a plain-text file that could be used to record server or other
significant site configuration changes if desired.  Two methods of access are
provided.

<COMMENT>(HTML=<P>)

<LIST>(NUMBERED)
<LE> Site-Log - open the file for editing, placing a
date/time/author timestamp at the top
<LE> Edit - open the file editing
<ENDLIST>

<P> The file name and/or location may be specified using HTTPD$SITELOG (see
<REFERENCE>(head_server_logical_names)).

<ENDLIST>

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

<HEAD1>(HTTPd Server Action\head_server_action)

<P> The server allows certain run-time actions to be initiated.  Many of these
functions can also be initiated from the command line, see
<REFERENCE>(head_httpd_control).

<P> When multiple servers are executing on a single node or within a cluster
a JavaScript-driven checkbox appears in the bottom left of the administration
menu. <EMPHASIS>(Checking that box applies any subsequently selected action to
all servers!\BOLD)

<HEAD>(Control Section\head_server_action_control)

<LIST>(NUMBERED)

<LE> <EMPHASIS>(Server Restart/restartNOW/Exit/exitNOW - \BOLD)

The difference between restart/exit and restartNOW/exitNOW is the former waits
for any current requests to be completed, while the latter does it immediately
regardless of any current connections.  If the browser has JavaScript enabled a
cautionary alert requesting confirmation is generated (otherwise there is no
confirmation).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Logging On/Off/Flush - \BOLD)
The HTTPD$LOG logical must be configured to allow access logging to be enabled
and disabled from this menu.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Caching On/Off/Purge - \BOLD)
Caching may be enabled and disabled in an ad hoc fashion using these controls.
When being disabled after being enabled all previous data is retained.  If
subsequently reenabled that data is then again available for use.  This allows
convenient assessment of the subject or even object benefits on the cahing.
If purged all entries in the cache are removed.

<ENDLIST>

<HEAD>(Configuration <EMPHASIS>(Action) Section\head_server_action_config)

<LIST>(NUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Statistics Zeroed - \BOLD)
All counters are zeroed (except the <EMPHASIS>(number-of-times-zeroed)
counter!)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Mapping Rules Reload - \BOLD)
Reloads the path mapping rules from the on-disk file into the running server,
clears the user SYSUAF mapping cache.

<P> <EMPHASIS>(Caution! \BOLD) If changing CGIplus script mapping it is
advised to restart the server rather than reload.  Some conflict is possible
when using new rules while existing CGIplus scripts are executing.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Path Authorization Reload - \BOLD)
Reloads the path authorization directives from the on-disk file into the
running server.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(User Authentication Cache Purge - \BOLD)
For efficiency reasons authenticated user information is cached for a limited
period within the running server.  All this cached information may be
completely purged using this action, forcing subsequent requests to be
reauthenticated from the on-disk database.

<ENDLIST>

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

<CHAPTER>(WATCH Facility\chapter_watch)

<P> The WATCH facility is a powerful adjunct in server administration. From
the administration menu it provides an <EMPHASIS>(online, real-time,
in-browser-window view of request processing in the running server\BOLD). The
ability to observe live request processing on an ad hoc basis, without
changing server configuration or shutting-down/restarting the server process,
makes this facility a great configuration and problem resolution tool. It
allows (amongst other uses)

<LIST>(UNNUMBERED)
<LE> assessment of mapping rules
<LE> assessment of authorization rules
<LE> investigation of request processing problems
<LE> observation of script interaction
<LE> general observation of server behaviour
<ENDLIST>

<P> A single client per server process can access the WATCH facility at any
one time.  It can be used in one of two modes.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> As a <EMPHASIS>(one-shot), one-off WATCH of a particular request.  This is
available from the <EMPHASIS>(Request Report) page of the Administration Menu. 
In this case the single indicated request is tagged to be WATCHed in all
categories (see below) for the duration of the request (or until the client
stops WATCHing).

<COMMENT>(HTML=<P>)

<LE> As described in the following chapter the server and all new requests
being processed are candidates for being WATCHed.  Categories are selected
before initiating the WATCH and the report can be generated for a user-specified
number of seconds or aborted at any time using the browser's <EMPHASIS>(stop)
button.

<ENDLIST>

<HEAD1>(Event Categories\head_reports_watch_categories)

<P> An <EMPHASIS>(event) is considered any significant point for which the
server code has a reporting call provided. These have been selected to provide
maximum information with minimum clutter and impact on server performance.
Obvious examples are connection acceptance and closure, request path
resolution, error report generation, network reads and writes, etc. Events are
collected together into groupings to allow clearly defined areas of interest
to be selected for reporting.

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

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

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

<COMMENT>(HTML=<P>)

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

<P> The report menu provides for the inclusion of any combination of the
following categories.

<HEAD>(Request\head_reports_watch_request)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Processing - \BOLD)
Each major step in a request's progress.  For example, path resolution and
final response status.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Header - \BOLD)
Provides the HTTP request header as a section of blank-line terminated text.

<COMMENT>(HTML=<P>)
<LE> <EMPHASIS>(Body - \BOLD)
In the case of HTTP POST or PUT methods any request body is displayed. It will
generally be URL-encoded but otherwise plain-text.

<ENDLIST>

<HEAD>(Response\head_reports_watch_response)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Processing - \BOLD)
Each major step in generating a response to the request. These generally
reflect calls to a major server module such as file CACHE, FILE access,
INDEX-OF, SSI processing, etc. One or more of these events may occur for each
request. For instance a directory listing will show an INDEX-OF call and then
usually a FILE call as any read-me file is accessed.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Header - \BOLD)
The blank-line terminated HTTP header to the response. Only server-generated
headers are included. Scripts that provide a full HTTP stream do not have the
header explicitly reported. The response body category must be enabled to
observe these (indicated by a STREAM notation).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Body - \BOLD)
The content of the response.   This is provided as a hexadecimal dump on the
left and with printable characters rendered on the right, 32 bytes per line.
Some requests also generate very large responses which will clutter output.
Generally this category would be used when investigating specific request
response body problems.

<ENDLIST>

<HEAD>(General\head_reports_watch_general)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Connection - \BOLD)
Each TCP/IP connection acceptance and closure. The connect shows which service
the request is using (scheme, host name and port).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Path Mapping - \BOLD)
This, along with the authorization report, provides one of the most useful
aspects of the WATCH facility. It comprises an event line indicating the path
to be mapped (it can also show a VMS file specification if a
<EMPHASIS>(reverse-mapping) has been requested). Then as each rule is
processed a summary showing current path, match <QUOTE>(Y)/<QUOTE>(N) for each
path template and any conditional, then the result and conditional. Finally an
event entry shows the resulting path, VMS file specification, any script name
and specification resolved. The path mapping category allows the administrator
to directly assess mapping rule processing with live or generated traffic.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Authorization - \BOLD)
When authorization is deployed this category shows the rules examined to
determine if a path is controlled, any authentication events in assessing
username and password, and the consequent group, user and request capabilities
(read and/or write) for that path.  No password information is displayed.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Error - \BOLD)
The essential elements of a request error report are displayed. This may
include a VMS status value and associated system message.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(CGI - \BOLD)
This category displays the generated CGI variable names and values as used by
subprocess and DECnet scripting, and by SSI documents.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(DCL - \BOLD)
Debugging scripts can sometimes present particular difficulties. This category
may help. It reports on all input/output streams with the subprocess
(SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, CGIPLUSIN).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(DECnet - \BOLD)
For the same reason as above this category reports all DECnet scripting
input/output of the DECnet link. In particular, it allows the observation of
the OSU scripting protocol.

<ENDLIST>

<HEAD>(Network\head_reports_watch_network)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Activity - \BOLD)
For each raw network read and write the VMS status code and size of the I/O is
recorded.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Data - \BOLD)
For each raw network read or write the contents are provided as a hexadecimal
dump on the left and with printable characters rendered on the right, 32 bytes
per line.

<ENDLIST>

<HEAD>(Other\head_reports_watch_other)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Timer - \BOLD)
Timers control the maximum periods each stage in request processing may
procede before the server aborts processing.  Input, output and keep-alive
timers are reported.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Logging - \BOLD)
Access logging events include log open, close and flush, as well as request
entries.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SSL - \BOLD)
If the Secure Sockets Layer image is in use this category provides a
indication of high-level activity.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Quotas - \BOLD)
Display the server process quotas with every WATCH event reported.  This can
add a lot of clutter to a report but may be useful when tracking down the cause
of resource exhaustion (of course there is a <QUOTE>(Catch 22) here - will
WATCH be able to report the quotas if resources have been exhausted!)

<ENDLIST>

<HEAD>(Proxy\head_reports_watch_proxy)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Processing - \BOLD)
Each major step during the serving of a proxied request.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Request Header - \BOLD)
The proxy server rebuilds the request originally received from the client. 
This category shows that rebuilt request, the one that is sent to the remote
server.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Request Body - \BOLD)
In the case of HTTP POST or PUT methods any request body is displayed.
This is provided as a hexadecimal dump on the left and with printable
characters rendered on the right, 32 bytes per line.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Response Header - \BOLD)
The blank-line terminated HTTP header to the response from the remote, proxied
server.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Response Body - \BOLD)
The content of the response sent from the remote server. This is provided as a
hexadecimal dump on the left and with printable characters rendered on the
right, 32 bytes per line.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Cache - \BOLD)
When proxy caching is enabled this category provides information on cache
reading (serving a request from cache) and cache loading (writing a cache file
using the response from a remote server).  It will provide a reason for any
request or response it does not cache, as well as report errors during file
processing.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Cache Maintenance - \BOLD)
This category is not related to request processing.  It allows routine and
reactive cache purging activities to be watched.

<ENDLIST>

<HEAD1>(Request Filtering\head_reports_watch_filter)

<P> By default all requests to all services are WATCHed. Fine control may be
exercised over exactly which requests are reported, allowing only a selected
portion of all requests being processed to be concentrated on, even on a live
and busy server. This is done by <EMPHASIS>(filtering) requests according the
following criteria.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Client - \BOLD)
The originating host name or address. Unless server DNS host name resolution
is enabled this must be expressed in dotted-decimal notation.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Service - \BOLD)
The service connected to. This includes the <EMPHASIS>(scheme) of the service
(i.e. <QUOTE>(http:), <QUOTE>(https:)), the host name (real or virtual), and
the port. The host name is the <EMPHASIS>(official) name of the service as
reported during server startup. As the port number is a essential part of the
service specification it must always be explicitly supplied or wildcarded.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Path/Track - \BOLD) Either, the request path, or a specific
track identifier string.  A path may be specified with a leading <QUOTE>(/) for
local paths or if WATCHing proxy requests with a full, or part of a full, URL. 
To WATCH requests associated with a particular access track (see
<REFERENCE>(head_log_tracking)) enter the track's unique identifier string
preceded by a dollar symbol (e.g. <QUOTE>($ORoKJAOef8sAAAkuACc)).

<ENDLIST>

<P> These filters are controlled using fully-specified or wildcarded strings.
Requests that do not match the filter are not reported. In the case of
originating client and destination service, requests are eliminated before ever
appearing in the report. Path and track filtering is slightly different,
requiring some request processing before the target can be determined.
Depending on the categories selected this may result in some events begin
displayed. It will be eliminated, with an accompanying explanatory message, as
soon the path or track identifier has been determined.

<P> The following examples are grouped in the same order as the categories
listed above; client, service and path.

<CODE_EXAMPLE>
  alpha.wasd.dsto.defence.gov.au
  *.wasd.dsto.gov.au  
  131.185.250.202
  131.185.250.*

  beta.wasd.dsto.defence.gov.au:8000
  beta.wasd.dsto.defence.gov.au:*
  http://*
  https:*
  *:80

  /ht_root/src/*
  /cgi-bin/*
  /web/*/cyrillic/*
  $ORoKJAOef8sAAAkuACc
  http://proxied.host.name/*
<ENDCODE_EXAMPLE>

<HEAD1>(Report Format\head_reports_watch_format)

<P> The following example illustrates the format of the WATCH report. It
begins with multi-line heading. The first two record the date, time and
official server name, with underline. The third provides the WASD server
version.  The fourth provides some TCP/IP agent information.  Lines following
can show OpenSSL version (if deployed), system infomation, server startup
command-line, and then current server process quotas.  The last three lines of
the header provide a list of the categories being recorded, the filters in use,
and the last, column headings described as follows: 

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(time\BOLD) the event was recorded
<LE> the <EMPHASIS>(module\BOLD) name of the originating source code
<LE> the <EMPHASIS>(line\BOLD) in the code module
<LE> a unique <EMPHASIS>(item\BOLD) number for each thread being WATCHed
<LE> event <EMPHASIS>(category\BOLD) name
<LE> free-form, but generally interpretable <EMPHASIS>(event\BOLD) data

<ENDLIST>

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

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

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

<COMMENT>(HTML=<P>)

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

<P> Note that some items also include a block of data. The request header
category does this, providing the blank-line terminated text comprising the
HTTP header. Rule mapping also provides a block of information representing
each rule as it is interpreted. Generally WATCH-generated information can be
distinguished from other data by it's uniform format and delimiting vertical
bars. Initiative and imagination is sometimes required to interpret the
free-form data but a basic understanding of HTTP serving and a little
consideration is generally all that is required to deduce the essentials
of any report.

<CODE_EXAMPLE><LITERAL>
  31-MAY-2000 18:20:25  WATCH REPORT  delta.wasd.dsto.defence.gov.au:80
  ---------------------------------------------------------------------
  HTTPd-WASD/7.0.0 OpenVMS/AXP SSL (30-MAY-2000 22:56:54.37 VMS 7.2-1 DECC 60290003)
  Compaq-TCP/IP TCPIP$IPC_SHR V5.0A-1 (20-MAY-1999 22:31:52.08)
  OpenSSL 0.9.5 28 Feb 2000 (5-MAR-2000 14:58:56.83)
  AlphaServer DS20 500 MHz VMS V7.2-1 (ODS-5 enabled, VMS NAML, VMS FIB)
  $ HTTPD /PRIORITY=4 /SYSUAF=(ID)
  AST:1995/2000 BIO:509/512 BYT:479200/499296 DIO:512/512 ENQ:504/512 FIL:295/300 PGFL:192992/200000 PRC:0/100 TQ:98/100
  BYTLM-available:495008 BYTLM-per-subproc:14592 (approx 26 subprocesses) BYTLM-net-accept:1024 BYTLM-net-listen:1024
  Watching: connect, request, response (19)
  Client: "*" Service: "*" Path: "*"
  |Time_______|Module__|Line|Item|Category|Event...|
  |18:20:46.91 NET      1626 0001 CONNECT  ACCEPT 131.185.250.108,47111 on https://131.185.250.203:443|
  |18:20:47.00 REQUEST  1211 0001 REQUEST  HEADER 285 bytes|
  GET /ht_root/ HTTP/1.0
  If-Modified-Since: Thursday, 07-Oct-99 03:51:23 GMT; length=4644
  Connection: Keep-Alive
  User-Agent: Mozilla/3.0Gold (X11; I; OSF1 V4.0 alpha)
  Pragma: no-cache
  Host: delta.wasd.dsto.defence.gov.au
  Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*

  |18:20:47.00 NET      1148 0001 CONNECT  VIRTUAL delta.wasd.dsto.defence.gov.au:443|
  |18:20:47.00 REQUEST  2270 0001 REQUEST  GET /ht_root/|
  |18:20:47.00 MAPURL   0312 0001 MAPPING  PATH /ht_root/|
  /ht_root/  ..  REDIRECT  /*.*.htmlx  /*.htmlx?httpd=ssi&__part=*
  /ht_root/  ..  PASS      /httpd/-/change/*  /httpd/-/change/*
  /ht_root/  ..  MAP       /htroot/*  /ht_root/*
  /ht_root/  ..  SET       /web/*   stmLF
  /ht_root/  ..  SET       /ht_root/*   stmLF
  /ht_root/  ..  MAP       /httpd-internal-icons/*  /httpd/-/*
  /ht_root/  ..  PASS      /ht_root/runtime/*  /ht_root/runtime/*
  /ht_root/  ..  PASS      /*/-/*  /ht_root/runtime/*/*
  /ht_root/  Y-  PASS      /ht_root/*  
  |18:20:47.00 MAPURL   0335 0001 MAPPING  RESULT /ht_root/ /ht_root/ HT_ROOT:[000000] - -|
  |18:20:47.00 CACHE    0604 0001 RESPONSE CACHE DSA811:[HT_ROOT.][000000]HOME.HTML|
  |18:20:47.00 NET      2427 0001 RESPONSE HEADER 231 bytes|
  HTTP/1.0 200 Success
  Server: HTTPd-WASD/7.0.0 OpenVMS/AXP Digital-TCPIP SSL
  Date: Wed, 31 May 2000 18:20:47 GMT
  Last-Modified: Tue, 30 May 2000 03:51:23 GMT
  Content-Type: text/html; charset=ISO-8859-1
  Content-Length: 4644

  |18:20:47.00 REQUEST  0407 0001 REQUEST  STATUS 200 rx:457 tx:5084 bytes 0.0000 seconds|
  |18:20:47.00 REQUEST  0252 0001 CONNECT  KEEP-ALIVE 131.185.250.108,47111|
  |18:20:52.06 NET      1502 0001 CONNECT  CLOSE 131.185.250.108,47111|
<ENDLITERAL><ENDCODE_EXAMPLE>
 
<HEAD1>(Usage Suggestions\head_reports_watch_suggestions)

<P> The following provides a brief explanation on the way WATCH operates and
any usage implications.

<P> A single client may be connected to the WATCH facility at any given time.
When connecting the client is sent an HTTP response header and the WATCH
report heading lines.  The request then remains connected until the WATCH
duration expires or the client overtly aborts the connection.  During this
period the browser behaves as if receiving a sometimes very slow, sometimes
stalled, plain-text document.  As the server processes WATCHable events the
text generated is sent to the WATCH-connected client.

<P> If the connection is aborted by the user some browsers will consider
document retrieval to be incomplete and attempt to reconnect to the service if
an attempt is made to print or save the resulting document. As the printing of
WATCH information is often quite valuable during problem resolution this
behaviour can result in loss of information and generally be quite annoying.
Appropriate use of the duration selector when requesting a report can work
around this, as at expiry the <EMPHASIS>(server) disconnects, browsers
generally interpreting this as legitimate end-of-document (when no
content-length has been specified).

<P> During report processing some browsers may not immediately update the
on-screen information to reflect received data without some application
activity. If scroll-bars are present on the document window manipulating
either the horizonal or vertical slider will often accomplish this. Failing
that minimizing then restoring the application will usually result in the most
recent information being visible.

<P> Browser <EMPHASIS>(reload/refresh) may be used to restart the report. A
browser will quite commonly attempt to remain at the current position in the
document, which with a WATCH report's sustained but largely indeterminate data
stream may take some time to reach. It is suggested the user ensure that any
vertical scroll-bar is at the beginning of the current report, then refresh
the report.

<P> Selecting a large number of categories, those that generate copious output
for a single event (e.g. response body) or collecting for extended periods
can all result in the receipt of massive reports. Some browsers do not cope
well with documents megabytes in size.

<NOTE>
WATCH reports are written using blocking I/O.
This means when large bursts of data are being generated (e.g. when WATCHing
network data, response bodies, etc.) significant granularity may be introduced
to server processing.  Also if the WATCH client fails or blocks completely
server processing could halt completely!  (This has been seen when WATCHing
through a firewall.)
<ENDNOTE>

<P> <EMPHASIS>(When supplying WATCH output as part of a problem report\BOLD)
please ZIP the file and include it an an e-mail attachment.  Mailers often
mangle the report format making it difficult to interpret.

<HEAD1>(Command-Line Use\head_reports_watch_cli)

<P> Although intended primarily as a tool for online use WATCH can be deployed
at server startup with a command-line qualifier and provide report output to
the server process log. This is slightly more cumbersome than the Web
interface but may still be useful in some circumstances. Full control over
event categories and filters is possible.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(/NOWATCH\BOLD) Disables the use of the online WATCH facility.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/WATCH=\BOLD) Enables the server WATCH facility, dumping to
standard output (and the server process log if detached).  When in effect the
online facility is unavailable.  The string supplied to the qualifier may
comprise four comma-separated components.  Only the first is manadatory.
Stated order is essential.  It will probably be necessary to enclose the
complete string in quotation marks.

<COMMENT>(HTML=<P>)

<LIST>(NUMBERED)
<LE> integer representing the categories to be reported
<LE> client filter
<LE> service filter
<LE> path filter
<ENDLIST>

<P> The category integer must be the bitwise-OR of the constants found in the
ADMIN.H source code header file.  The end of the category list in the on-line
WATCH report header contains a parenthesized integer.  This is the number
representing the enabled categories for that report and can be used for those
same categories from the command line.

<P> The following examples illustrate the command-line WATCH specification.

<CODE_EXAMPLE>
  /NOWATCH
  /WATCH=88
  /WATCH="88,*,*,/cgi-bin/*"
<ENDCODE_EXAMPLE>

<ENDLIST>

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