WASD Hypertext Services - Technical Overview

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. 

  Server Administration Graphic

In addition a Web Update facility allows some administration of file system portions of the Web. See 19 - HTTPd Web Update. 

15.1 - Authorization

The section 11.1 - SYSUAF/Identifier Authentication provides a quick guide to setting up authorization for server administration purposes. 

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:

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

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 12.9.3 - Nil-Access VMS Accounts. 

  [VMS]
  /httpd/-/admin/*  #localhost,~username,r+w

If SSL is in use (see 14 - Secure Sockets Layer) 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:

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

When using the 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 19 - HTTPd 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]).

  [VMS]
  /httpd/-/admin/*  #localhost,~username,r+w
  /ht_root/local/*  #localhost,~username,r+w

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

  [VMS]
  /httpd/-/admin/control/*  #localhost,~username,r+w
  [WORLD]
  /httpd/-/admin/* r

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

This provision exists for only four foreseeable situations:

1. ad hoc server configuration
2. initial configuration of the authentication environment
3. loss of the administrator's password
4. demonstration/experimentation purposes

If performing the initial authentication configuration make sure the HT_AUTH logical is correctly defined when planning to use HTA databases. 

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:

  $ HTTPD = "$HT_EXE:HTTPD.EXE"
  $ SPAWN /WAIT HTTPD /NOLOG /SERVICE=8088 /PROMISCUOUS

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. 

  $ SPAWN /WAIT HTTPD /NOLOG /SERVICE=8088 /PROMISCUOUS=VERYCAUTIOUS

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

  http://host:port/httpd/-/admin/

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. 

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. 

  [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

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. 

15.3 - HTTPd Server Reports

The server provides a number of internally generated reports. 

It is possible to use this facility standalone, without configuring authorization, see 15.2 - Breaking-in To The Server! . 

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

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

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

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

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

6. Path Authorization - If authorization is in use (see 12 - Authentication and Authorization) this report lists the paths with associated authorization and access control. 

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

8. Cache - Allows monitoring of cache behaviour and performance, as well as the files currently in the cache.  For further information see 17 - Cache. 

9. DCL Scripting

   Provides some DCL, CGI and CGIplus scripting information. 

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

   • 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 soft-limit specifies how many CGIplus scripts are allowed to continue existing before the least used is deleted and the 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 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. 

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

   • If any subprocesses are associated with any data structure a 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 does not force a subprocess to delete, so a second button forces all subprocesses to delete immediately.  This can be used to forceably clear errant scripts, etc., but be warned script processing is indiscrimately stopped! 

10. DECnet Scripting

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

    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. 

    Purge and force buttons allow current links to be broken after request completion or forcibly disconnected. 

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

12. Process - Lists all processes on the current system owned by the server account.  From this list a process can be selected to have a "SHOW PROCESS /ALL" performed on it, displayed on a report page. 

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

14. Request

    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 one-shot WATCH-processing reports from this page (see 16 - WATCH Facility). 

    Another diagnostic tool is available from the same link, the WATCH-peek Report.  Two "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 "double-dot" accesses the internals then begins a one-shot WATCH-processing report. 

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

16. Activity

    Provide a graphical snapshot of server activity of a given period. 

    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 greyed area indicates no data available for that time (i.e. before the latest server startup, or in the future). 

    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 peak of the number of minutes sampled for display.  This better represents the load on the server than would a mean of those samples. 

    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. 

    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. 

    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. 

    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. 

      Server Activity Graphic

17. WATCH - This report provides an online, real-time, in-browser-window view of request processing on the running server.  See 16 - WATCH Facility for details. 

15.4 - HTTPd Server Revise

The server provides a comprehensive configuration revision facility. 

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

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

3. Messages - 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 15.5 - HTTPd Server Action). 

4. Mapping - 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 15.5 - HTTPd Server Action). 

5. Path Authorization - 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 15.5 - HTTPd Server Action). 

6. User Authentication - User authentication comprises a number of dialogues that allow the WASD-specific (HTA) authentication databases to be administered.  These include:
   • creating databases
   • deleting databases
   • accessing databases for administering usernames
   • listing usernames within databases
   • adding usernames
   • deleting usernames
   • modifying username permissions and other data
   • reseting in-server (cached) authentication information

   Chapter 12 - Authentication and Authorization covers authentication detail. 

7. Site Log - 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. 
   1. Site-Log - open the file for editing, placing a date/time/author timestamp at the top
   2. Edit - open the file editing

   The file name and/or location may be specified using HTTPD$SITELOG (see Logical Names). 

The server allows certain run-time actions to be initiated.  Many of these functions can also be initiated from the command line, see 5.3.2 - Server Command Line Control. 

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.  Checking that box applies any subsequently selected action to all servers! 

Control Section

1. Server Restart/restartNOW/Exit/exitNOW - 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). 

2. Logging On/Off/Flush - The HTTPD$LOG logical must be configured to allow access logging to be enabled and disabled from this menu. 

3. Caching On/Off/Purge - 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. 

1. Statistics Zeroed - All counters are zeroed (except the number-of-times-zeroed counter!)

2. Mapping Rules Reload - Reloads the path mapping rules from the on-disk file into the running server, clears the user SYSUAF mapping cache. 

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

3. Path Authorization Reload - Reloads the path authorization directives from the on-disk file into the running server. 

4. User Authentication Cache Purge - 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.