WASD Hypertext Services - Technical Overview

The WATCH facility is a powerful adjunct in server administration. From the Server Administration facility (18 - Server Administration) it provides an online, real-time, in-browser-window view of request processing in the running server. 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)

assessment of mapping rules

assessment of authorization rules

investigation of request processing problems

observation of script interaction

general observation of server behaviour

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

• As a one-shot, one-off WATCH of a particular request. This is available from the Request Report page of the Server Administration facility. 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).

• 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 stop button.

Options immediately below the duration selector allows the WATCH output to concurrently be included in the server process log. This allows a permanent record (at least as permanent as server logs) to be simply produced.

19.1 - Server Instances

With a single instance (6.2 - Server Instances) access to WATCH is always through the one server process. If multiple instances are configured WATCH requests, in common with all others, will be serviced by any one of the associated processes depending on the indeterminate current state of the round-robin distribution.

This is often an issue for request WATCHing. The simplest scenario involves two instances. When the WATCH report is activated it will be serviced by the first process, when the request wishing to be WATCHed is accessed it (in the absence of any other server activity) will be serviced by the other process and will not be reported by WATCH on the first.

There is no simple solution for this issue as the round-robin distribution of requests is determined by the network device driver. When debugging server or script behaviour often the simplest solution is to temporarily reset to one the number of instances running on the system. See 18.3 - Server Instances, 18.6 - HTTPd Server Action and 5.5.2.6 - Instances.

19.2 - Event Categories

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

  WATCH Selection Graphic

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

Request

• Processing - Each major step in a request's progress. For example, path resolution and final response status.

• Header - Provides the HTTP request header as a section of blank-line terminated text.

• Body - The content (if a POST or PUT method) of the request. This is provided as a hexadecimal dump on the left and with printable characters rendered on the right, 32 bytes per line.

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

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

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

• Connection - Each TCP/IP connection acceptance and closure. The connect shows which service the request is using (scheme, host name and port).

• Path Mapping - 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 reverse-mapping has been requested). Then as each rule is processed a summary showing current path, match "Y"/"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.

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

• Error - The essential elements of a request error report are displayed. This may include a VMS status value and associated system message.

• CGI - This category displays the generated CGI variable names and values as used by various forms of scripting and by SSI documents, as well as the processing of the response header returned by scripts.

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

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

• Activity - For each raw network read and write the VMS status code and size of the I/O is recorded.

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

• Match - Shows a significant level of detail during string matching activities. May be useful during mapping, authorization and conditional processing.

• Logging - Access logging events include log open, close and flush, as well as request entries.

• SSL - If the Secure Sockets Layer image is in use this category provides a indication of high-level activity.

• Quotas - Display available server process resource quotas with significant events.

• Processing - Each major step during the serving of a proxied request.

• Request Header - 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.

• Request Body - 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.

• Response Header - The blank-line terminated HTTP header to the response from the remote, proxied server.

• Response Body - 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.

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

• Cache Maintenance - This category is not related to request processing. It allows routine and reactive cache purging activities to be watched.

If the server has been compiled using the WATCH_MOD=1 macro a set of module WATCHing statements is included. These provide far more detailed processing information than available with the generic WATCH, are intended primarily for debugging the server during development and testing. This is considered a specialized tool, with the quantity and level of detail produced most likely proving counter-productive in addressing general site configuration issues. The module items are shown below the usual WATCH items.

19.3 - Request Filtering

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 filtering requests according the following criteria.

• Client - The originating host name or address. Unless server DNS host name resolution is enabled this must be expressed in dotted-decimal notation.

• Service - The service connected to. This includes the scheme of the service (i.e. "http:", "https:"), the host name (real or virtual), and the port. The host name is the 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.

• Path/Track - Either, the request path, or a specific track identifier string. A path may be specified with a leading "/" 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 (6.11.6 - Access Tracking) enter the track's unique identifier string preceded by a dollar symbol (e.g. "$ORoKJAOef8sAAAkuACc").

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.

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

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

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 information, 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:

time the event was recorded

the module name of the originating source code

the line in the code module

a unique item number for each thread being WATCHed

event category name

free-form, but generally interpretable event data

  WATCH Report Graphic

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.

  29-MAY-2003 08:54:59  WATCH REPORT  wasd.dsto.defence.gov.au:80
  ---------------------------------------------------------------
  HTTPd-WASD/8.3.0 OpenVMS/AXP SSL (26-MAY-2003 08:07:52.96)
  Compaq TCPIP$IPC_SHR V5.3-18 (29-MAR-2002 05:01:04.60)
  OpenSSL 0.9.7b 10 Apr 2003 (12-APR-2003 09:31:08.21)
  $ CC (V7.3-1/60590001) /DECC /STAND=RELAXED_ANSI /PREFIX=ALL /OPTIMIZE /NODEBUG /WARNING=(NOINFORM,DISABLE=(PREOPTW)) /DEFINE=(WASD_VMS_V6,SESOLA,WATCH_CAT=1,WATCH_MOD=1)
  AlphaServer 1200 5/533 4MB with 1 CPU and 256MB running VMS V7.3-1 (ODS-5 enabled, VMS NAML, VMS FIB)
  $ HTTPD /PRIORITY=4 /SYSUAF=ID/PROFILE/PERSONA
  AST:1993/2000 BIO:1996/2000 BYT:671728/749424 DIO:1000/1000 ENQ:451/500 FIL:291/300 PGFL:472336/500000 PRC:0/100 TQ:97/100
  DCL Scripting: detached, as HTTP$NOBODY, PERSONA enabled
  Process: HTTPd:80 HT_ROOT:[STARTUP]STARTUP_SERVER.COM;5 HT_ROOT:[LOG_SERVER]WASD_20030520094358.LOG;1
  Instances: WASD::HTTPd:80
  Watching: connect, request, req-header, response, res-header, error (603)
  Client: "" Service: "" Path: ""
  |Time_______|Module__|Line|Item|Category__|Event...|
  |08:55:06.74 NET      1839 0001 CONNECT    ACCEPTED wasd,49846 on http://131.185.30.1:80 BG5372:|
  |08:55:06.75 REQUEST  1751 0001 REQ-HEADER HEADER 608 bytes|
  GET /web/colloquia/ HTTP/1.1
  Host: wasd.dsto.defence.gov.au
  User-Agent: Mozilla/5.0 (X11; U; OpenVMS AlphaServer_1200_5/533_4MB; en-US; rv:1.3) Gecko/20030313
  Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,video/x-mng,image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1
  Accept-Language: en-us,en;q=0.5
  Accept-Encoding: gzip,deflate,compress;q=0.9
  Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
  Keep-Alive: 300
  Connection: keep-alive
  Referer: http://wasd.dsto.defence.gov.au/home.html
  If-Modified-Since: Fri, 10 Nov 2000 06:33:58 GMT
  Cache-Control: max-age=0
  
  |08:55:06.75 NET      1313 0001 CONNECT    VIRTUAL wasd.dsto.defence.gov.au:80|
  |08:55:06.75 REQUEST  2701 0001 REQUEST    GET /web/colloquia/|
  |08:55:06.75 CACHE    0466 0001 RESPONSE   CACHE search 8EE655F806C11A98E0B51D52FFE5B269|
  |08:55:06.77 CACHE    0712 0001 RESPONSE   CACHE revalidate WEB:[COLLOQUIA]INDEX.HTML;|
  |08:55:06.77 CACHE    0717 0001 RESPONSE   CACHE hit volatile WEB:[COLLOQUIA]INDEX.HTML;|
  |08:55:06.77 NET      2167 0001 RES-HEADER HEADER 249 bytes|
  HTTP/1.0 200 OK
  Server: HTTPd-WASD/8.3.0 OpenVMS/AXP SSL
  Date: Wed, 28 May 2003 23:25:06 GMT
  Last-Modified: Fri, 10 Nov 2000 06:33:58 GMT
  Content-Type: text/html; charset=ISO-8859-1
  Content-Length: 1596
  Connection: Keep-Alive
  Keep-Alive:
  
  |08:55:06.77 REQUEST  0682 0001 REQUEST    STATUS 200 rx:608 tx:1845 bytes 0.0208 seconds|
  |08:55:06.77 REQUEST  0326 0001 CONNECT    KEEP-ALIVE wasd,49846|
  |08:55:12.84 NET      2027 0001 CONNECT    CLOSE wasd,49846|
  |08:55:29.46 end|

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

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.

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 server disconnects, browsers generally interpreting this as legitimate end-of-document (when no content-length has been specified).

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.

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

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

---

When supplying WATCH output as part of a problem report please ZIP the file and include it an an e-mail attachment. Mailers often mangle the report format making it difficult to interpret.

19.6 - Command-Line Use

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.

• /NOWATCH Disables the use of the online WATCH facility.

• /WATCH= 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.
  • LIST - The LIST keyword provides a list of all the categories (items) available for WATCHing.

  • NOSTARTUP - This keyword suppresses WATCH output until the server is ready to process requests. It must be the leading keyword.

  • items - A parenthesized, comma-separated list of category keywords. Available keywords can be displayed using the LIST facility.

  • filters - A client, service and path filters can be provided following the specification of required items. They must be provided in the order listed above. Leading filters that are not required must be provided as single, asterisk wildcards. WATCH parameter with filters containing forward-slashes will require quoting.

The following examples illustrate the command-line WATCH specification.

  /NOWATCH
  /WATCH=NOSTARTUP,ITEMS=(REQUEST,RESPONSE,MAPPING)
  /WATCH="ITEMS=(REQUEST,RESPONSE,ERROR),*,*,/cgi-bin/*"
  /WATCH=LIST