(online graphic) (HTML/ON) (....................................................................) (HTTPd Server Revise\hd_server_revise)

The server provides a comprehensive configuration revision facility. (UNNUMBERED) (Configuration - \BOLD) A form-driven interface allows the current configuration of the server to be altered online. 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 its 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. (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. (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 ((hd_server_action)). (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 ((hd_server_action)). (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 ((hd_server_action)). (User Authentication - \BOLD) User authentication comprises a number of dialogues that allow the WASD-specific (HTA) authentication databases to be administered. These include:

(SIMPLE) 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 (cr_authorization) covers authentication detail. (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. (NUMBERED) Site-Log - open the file for editing, placing a date/time/author timestamp at the top Edit - open the file editing

The file name and/or location may be specified using the logical name WASD_SITELOG. (Enabling Server Access\hd_server_access)

Many of the server activites listed above require server account write access to the directory in which the configuration files are stored. Where an autononmous scripting account is in use this poses minimal threat to server configuration integrity. (NUMBERED) Specifically map the /wasd_root/local/ path and mark it as access always requiring authorization (ensure this is one on the first mappings in the file and certainly before any other /wasd_root/ ones). # WASD_CONFIG_MAP pass /wasd_root/local/* auth=all Add appropriate authorization rules (example from (HREF=[-.config]config.sdml!../config/#cr_auth_config)([-.CONFIG]DOC_config.sdml)). # WASD_CONFIG_AUTH ["Web Admin"=WASD_WEBADMIN=id] /httpd/-/admin/* r+w /wasd_root/local/* r+w Update access to the directory can be applied using the SECHAN utility ((hd_sechan)). $ SECHAN /WRITE WASD_ROOT:[000000]LOCAL.DIR $ SECHAN /WRITE WASD_ROOT:[LOCAL] Load the new mapping and authorization rules. $ HTTPD /DO=MAP $ HTTPD /DO=AUTH=LOAD (Alternative Using /PROFILE\hd_server_access_profile)

If a site is using SYSUAF authentication and security profiles enabled using the /PROFILE startup qualifier ((hd_auth_security_profile)) then a more restrictive set up is possible, retaining the default no-access to the [LOCAL] directory. This relies on the administering account(s) having read and write access to the [LOCAL] directory. It is then not necessary to grant that to the server account. It is possible to limit the application of VMS user profiles. This is an example. # WASD_CONFIG_MAP set /wasd_root/local/* profile auth=all set * noprofile

To use this approach perform steps 1, 2 and 4 from above, substituting the following for step 3. $ SECHAN /PACKAGE WASD_ROOT:[000000]LOCAL.DIR $ SECHAN /PACKAGE WASD_ROOT:[LOCAL] $ SECHAN /CONTROL WASD_ROOT:[000000]LOCAL.DIR (....................................................................) (HTTPd Server Action\hd_server_action)

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

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!\BOLD) (Control Section\hd_server_action_control) (UNNUMBERED) (Server Restart/restartNOW/restartQuiet/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. The restartQuiet variant continues processing until demand drops to zero for more than one second at which point it commences restart. If the browser has JavaScript enabled a cautionary alert requesting confirmation is generated (otherwise there is no confirmation). (Logging On/Off/Flush - \BOLD) The WASD_CONFIG_LOG logical must be configured to allow access logging to be enabled and disabled from this menu. (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. (Instance Startup - \BOLD) An instance value may be set that overrides the configuration directive [InstanceMax] at next startup. This may be used to change the number of server processes on an ad hoc basis. Reset to (max) to return to configuration control. Note that this can be applied to the current node only or to all servers within a cluster, and that a subsequent restart is required. ((/DO=) Button and Field - \BOLD) Provides a on-line facility parallel to that provided by the command-line /DO qualifier ((hd_admin_do_cli)). Any directive available via the command-line can be entered using this interface and applied on a per-node or per-cluster basis. (Configuration (Action) Section\hd_server_action_config) (UNNUMBERED) (Statistics Zeroed - \BOLD) All counters are zeroed (except the (number-of-times-zeroed) counter!) (Mapping Rules Reload - \BOLD) Reloads the path mapping rules from the on-disk file into the running server, clears the user SYSUAF mapping cache.

(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. (Path Authorization Reload - \BOLD) Reloads the path authorization directives from the on-disk file into the running server. (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. (--------------------------------------------------------------------) (HTTPd Command Line\hd_admin_do_cli)

A foreign command for the HTTPD control functionality will need to be assigned in the adminstration users' LOGIN.COM, for example: $ HTTPD == "$WASD_EXE:HTTPD" or (perhaps more likely) $ HTTPD == "$WASD_EXE:HTTPD_SSL"

Some control of the executing server is available from the DCL command line on the system on which it is executing. This functionality, (via the /DO= qualifier\BOLD), is available to the privileged user.

These directives are communicated from the command-line (and Server Administration page analogue - (hd_server_action_control)) to the per-node or per-cluster servers using the Distributed Lock Manager. On pre-VMS V8.2 the command buffer is limited to 15 bytes. From VMS V8.2 the buffer space available is 63 bytes. In a cluster all systems must support the larger buffer before WASD enables it. The smaller buffer space limits some of the directives that take free-form parameters (e.g. /DO=DCL=PURGE=USER=DANIEL). (Multi-Server/Cluster-Wide\hd_server_multiple)

If multiple servers are executing on a host or cluster it is possible to control all of them by adding the /CLUSTER or /ALL qualifiers. Of course, these commands are available from batch jobs as well as interactively. In a clustered WASD environment the same functionality is available via checkboxes from the online Server Administration facility. (Need it to be jogged?\hd_server_do_help)

Can't quite remember what it can (and by implication can't) do? $ HTTPD /DO=HELP (Server Log Annotation\hd_admin_do_note)

Significant server events (e.g. restart, exit, mapping rule change) can often benefit (post-mortem :-) from an annotation in the server process log, especially in a production environment. The command-line /NOTE="()" can be used to insert the supplied string as an ad hoc annotation, or in conjunction with a /DO=".." CLI command. $ HTTPD /NOTE="just a note test!" $ HTTPD /DO=RESTART /NOTE="adding services ""download."" and ""mail."""

The server process log annotation appear as follows. %HTTPD-I-NOTE, 10-DEC-2017 22:32:30, just a note test! %HTTPD-I-NOTE, 10-DEC-2017 22:33:05, adding services "download." and "mail."

Note may also be inserted from the Server Admin main page by using the [/DO=] button and field and prefixing the string with /NOTE= (string delimitting quotation marks are not required). Using the Server Admin page annotation and commands cannot be combined. (Accounting\hd_admin_do_accounting)

Server counters may be zeroed. These counters are those visible from the (statistics) Server Admininstration item and when using the HTTPDMON utility. $ HTTPD /DO=ZERO

The HTTPDMON utility displays a status line during startup or server exit on error. For example: KLAATU:: 1 HTTPDMON v2.6.0 AXP Friday, 21-SEP-2018 21:40:54 Process: WASD:80 PID: 00001F9B User: HTTP$SERVER Version: 11.3.0 Up: 6 18:21:20.96 CPU: 0 00:07:25.54 Startup: 55 Exit: %X00000001 (8< snip 8<) Rx: 1,365,809 (0 err) Tx: 26,965,420 (0 err) (477kB/s) STATUS: %HTTPD-I-STARTUP, 21-SEP-2018 21:40:52, WASD:80

On occasion this can status message become constantly displayed (e.g. command-line misoperation) with $ HTTPD /DO=ZERO=STATUS restoring normal request information. (Alignment Faults\hd_admin_do_align)

On Alpha and Itanium platforms alignment faults can be a significant performance issue and considerable effort has been invested in completely eliminating them. This was done using a internal reporting tool (primarily intended for the WASD developer) available from the Server Admin interface. Defining the logical name WASD_ALIGN_MAP to be a linker map of the build provides additional information. $ HTTPD /DO=ALIGN=START $ HTTPD /DO=ALIGN=STOP $ HTTPD /DO=ALIGN=ZERO $ HTTPD /DO=ALIGN=FAULT=1 (Authentication\hd_admin_do_auth)

See (cr_authorization).

The authorization rule file (HTTP$AUTH) may be reloaded using either of these variants. $ HTTPD /DO=AUTH $ HTTPD /DO=AUTH=LOAD

The authentication cache may be purged, resulting in re-authentication for all subsequent authorization-controlled accesses. This may be useful when disabling authorization or if a user has been locked-out due to too many invalid password attempts ((hd_auth_cache)). $ HTTPD /DO=AUTH=PURGE

A (skeleton-key) username and password may be entered, amongst things allowing access to the Server Administration facility ((cr_server_admin)). $ HTTPD (/DO=AUTH=SKELKEY=_:[:]) (Cache\hd_admin_do_cache)

Server cache control may also be exercised from the Server Administration page ((cr_server_admin)). The file cache (see ([-.CONFIG]DOC_config.sdml) document, (Cache Configuration) section) may be enabled, disabled and have the contents purged (declared invalid and reloaded) using $ HTTPD /DO=CACHE=ON $ HTTPD /DO=CACHE=OFF $ HTTPD /DO=CACHE=PURGE (Configuration Check\hd_admin_do_check)

Changes to configuration files can be validated at the command-line before reload or restart. This detects and reports any syntactical and fatal configuration errors but of course cannot check the (intent) of the rules. $ HTTPD /DO=AUTH=CHECK $ HTTPD /DO=CONFIG=CHECK $ HTTPD /DO=GLOBAL=CHECK $ HTTPD /DO=MAP=CHECK $ HTTPD /DO=MSG=CHECK $ HTTPD /DO=SERVICE=CHECK

The (config) check sequentially processes each of the (authorization), (global), (mapping), (message) and (service) configuration files.

If additional server startup qualifiers are required to enable specific configuration features then these must also be provided when checking. For example: $ HTTPD /DO=AUTH=CHECK /SYSUAF /PROFILE (DCL/Scripting Processes\hd_admin_do_dcl)

These commands can be useful for flushing any currently executing CGIplus applications from the server, enabling a new version to be loaded with the next access. See (Scripting Environment) document.

All scripting processes, busy with a request or not, can be deleted (this may cause the client to lose data). $ HTTPD /DO=DCL=DELETE

A gentler alternative is to delete idle processes and mark busy ones for deletion when completed processing. $ HTTPD /DO=DCL=PURGE

For VMS V8.2 and later, a more selective DELETE and PURGE is possible. A user name, script name, or script file name can be supplied and only matching tasks have the specified action peformed. $ HTTPD /DO=DCL=PURGE=USER=(username) $ HTTPD /DO=DCL=PURGE=SCRIPT=(script-path) $ HTTPD /DO=DCL=PURGE=FILE=(script-file-name) (DECnet Scripting Connections\hd_admin_do_decnet)

All DECnet connections, busy with a request or not, can be disconnected (this may cause the client to lose data). $ HTTPD /DO=DECNET=DISCONNECT

Purging is a better alternative, disconnecting idle tasks and marking busy ones for disconnection when complete. $ HTTPD /DO=DECNET=PURGE (Hhelppp!\hd_server_do_help2) $ HTTPD /DO=HELP o ALIGN= START, STOP, ZERO with ([,,]) o AUTH reload authorization file o AUTH=CHECK elementary check of authorization file o ZERO zero all accounting o ZERO=NOTICED zero the ('errors noticed') accounting o ZERO=PROXY zero proxy accounting $ (HTTP/2 Connection\hd_admin_do_http2)

Disconnect idle HTTP/2 connections. $ HTTPD /DO=HTTP2=PURGE

All HTTP/2 connections can be disconnected (this may cause clients to lose data), or a specific connection number. $ HTTPD /DO=HTTP2=PURGE=ALL $ HTTPD /DO=HTTP2=PURGE=(number) (Instances\hd_admin_do_instance)

The number of server instances (see (hd_server_instances)) may be set from the command line. This overrides any configuration file directive and applies at the next startup. Any configuration directive value may be used from the command line. $ HTTPD /DO=INSTANCE=MAX $ HTTPD /DO=INSTANCE=CPU $ HTTPD /DO=INSTANCE=(integer)

(Note that the server must be restarted for this to take effect\BOLD), that this can be applied to the current node only or to all servers within a cluster, and that it remains in effect until explicitly changed to (MAX) allowing the WASD_CONFIG_GLOBAL configuration directive [InstanceMax] to once again determine the number of instances required. The same functionality is available from the Server Administration page ((hd_server_action)).

There are also directives to assist with WATCH activities ((hd_watch_instances)). $ HTTPD /DO=INSTANCE=PASSIVE $ HTTPD /DO=INSTANCE=ACTIVE (Instance Status\hd_admin_do_status)

Multi-instance (see (hd_server_instances)) status (see (hd_instance_status)) can be reported from the command line using $ HTTPD /DO=STATUS

In addition, stale entries in the status table may be purged using $ HTTPD /DO=STATUS=PURGE and the table completely emptied then repopulated over the next minute using $ HTTPD /DO=STATUS=RESET (Logging\hd_admin_do_logging)

Server logging control may also be exercised from the server administration menu ((cr_server_admin)).

Open the access log file(s). $ HTTPD /DO=LOG=OPEN

Close the access log file(s). $ HTTPD /DO=LOG=CLOSE

Close then reopen the access log file(s). $ HTTPD /DO=LOG=REOPEN

Unwritten log records may be flushed to the file(s). $ HTTPD /DO=LOG=FLUSH (Mapping\hd_admin_do_map)

See (HREF=[-.config]config.sdml!../config/#cr_mapping_rule)([-.CONFIG]DOC_config.sdml).

The mapping rule file (WASD_CONFIG_MAP) may be reloaded using either of these variants. $ HTTPD /DO=MAP $ HTTPD /DO=MAP=LOAD (Network Connection\hd_admin_do_network)

Disconnect idle (persistent) connections. $ HTTPD /DO=NET=PURGE

All network connections can be disconnected (this may cause clients to lose data), a specific connection number and those matching the specified URI. $ HTTPD /DO=NET=PURGE=ALL $ HTTPD /DO=NET=PURGE=(number) $ HTTPD /DO=NET=PURGE=URI=(pattern)

Additionally, network connection acceptance can be suspended (leaving in-progress requests to complete), suspended and in-progress disconnected, and resumed. $ HTTPD /DO=NET=SUSPEND $ HTTPD /DO=NET=SUSPEND=NOW $ HTTPD /DO=NET=RESUME (Shutdown and Restart\hd_admin_do_shutdown)

Server shutdown may also be exercised from the Server Administration page ((cr_server_admin)).

The server may be shut down, without loss of existing client requests. Connection acceptance is stopped and any existing requests continue to be processed until conclusion. $ HTTPD /DO=EXIT

The server may be immediately and unconditionally shut down. $ HTTPD /DO=EXIT=NOW

The server may be restarted, without loss of existing client requests. Connection acceptance is stopped and any existing requests continue to be processed until conclusion. This effectively causes the server to exit normally and the DCL (wrapper) procedure to restart it. $ HTTPD /DO=RESTART

The (now) variant restarts the server immediately regardless of existing connections. $ HTTPD /DO=RESTART=NOW

The when-(quiet) variant restarts the server whenever request processing drops to zero for more than one second. It allows (perhaps non-urgent) changes to be put into effect through restart when everything has gone (quiet) and no demands are being placed on the server. $ HTTPD /DO=RESTART=QUIET

Significant server events such as these are prime candidates for server log annotation! $ HTTPD /DO=RESTART=NOW /NOTE="Restarting the server just so I can note it :-)" (Secure Sockets Layer\hd_admin_do_ssl)

If the optional SSL component is installed and configured these directives become effective.

If X.509 authentication is enabled the Certificate Authority (CA) verification list can be reloaded. $ HTTPD /DO=SSL=CA=LOAD

Server certificates, after being updated, may be reloaded into the running services (i.e. without restart). This is a synonym for /DO=SERVICE=LOAD. $ HTTPD /DO=SSL=CERT=LOAD

If a private key password is not included with the encode key it is requested by the server during startup. The following example shows the directive and the resulting prompt. When entered the password is not echoed. $ HTTPD /DO=SSL=KEY=PASSWORD Enter private key password []:

Service SSL parameters may be (re)loaded from the configuration file and modified on the running server (i.e. without restart), for all existing services or just a single, specified service. $ HTTPD /DO=SSL=SERVICE=LOAD $ HTTPD /DO=SSL=SERVICE=LOAD=(host:port) (Throttle\hd_admin_do_throttle)

Unconditionally release all queued requests for immediate processing. $ HTTPD /DO=THROTTLE=RELEASE

Unconditionally terminate all requests queued waiting for processing. Clients receive a 503 (server too busy) response. $ HTTPD /DO=THROTTLE=TERMINATE

For VMS V8.2 and later, a more selective RELEASE and TERMINATE is possible. A user name or script name can be supplied and only matching requests have the specified action peformed. $ HTTPD /DO=THROTTLE=TERMINATE=REMOTE=(pattern) $ HTTPD /DO=THROTTLE=TERMINATE=SCRIPT=(pattern) (WebSocket\hd_admin_do_websocket)

Unconditionally disconnects all WebSocket applications. $ HTTPD /DO=WEBSOCKET=DISCONNECT

For VMS V8.2 and later, more selective disconnects are possible. Disconnects WebSocket applications with connection number, with matching script names, and with matching scripting account usernames, respectively. $ HTTPD /DO=WEBSOCKET=DISCONNECT=(number) $ HTTPD /DO=WEBSOCKET=DISCONNECT=SCRIPT=(pattern) $ HTTPD /DO=WEBSOCKET=DISCONNECT=USER=(pattern) (--------------------------------------------------------------------) (WATCH Facility\cr_watch)

The WATCH facility is a powerful adjunct in server administration. From the Server Administration facility ((cr_server_admin)) it provides an (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) (SIMPLE) 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. (UNNUMBERED) 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. (Server Instances\hd_watch_instances)

With a single instance (see (hd_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 momentary 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.

The solution is to suspend the round-robin request processing for the period of the WATCH activity. This does not shut any instance down but instead makes all but the supervisor instance quiescent. (Technically, it dequeues all the listening I/Os from non-supervisor instance server sockets, making the TCP/IP network driver send all connection requests to the one instance left with listening I/Os.) It is just a matter of making the non-supervisor instances active again when the WATCH activity is concluded.

This may be done from the command-line using $ HTTPD /DO=INSTANCE=PASSIVE $ HTTPD /DO=INSTANCE=ACTIVE or using the Server Administration facility ((cr_server_admin)) where there are [Active] and [Passive] buttons available when multiple instances are in use. Neither transition disrupts any requests being established or in-progress. (Event Categories\hd_watch_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. (....................................................................) (HTML=

  WATCH Selection Graphic

(HTML/OFF)

(online graphic) (HTML/ON) (....................................................................)

The report menu provides for the inclusion of any combination of the following categories. (Request\hd_watch_request) (UNNUMBERED) (Processing - \BOLD) Each major step in a request's progress. For example, path resolution and final response status. (Header - \BOLD) Provides the HTTP request header as a section of blank-line terminated text. (Body - \BOLD) 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. (Response\hd_watch_response) (UNNUMBERED) (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. (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). (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. (General\hd_watch_general) (UNNUMBERED) (Connection - \BOLD) Each TCP/IP connection acceptance and closure. The connect shows which service the request is using (scheme, host name and port). (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 (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 - \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. (Error - \BOLD) The essential elements of a request error report are displayed. This may include a VMS status value and associated system message. (CGI - \BOLD) 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 - \BOLD) Debugging scripts can sometimes present particular difficulties. This category may help. It reports on all input/output streams with the process (SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, CGIPLUSIN). (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. (WebDAV - \BOLD) Provides WebDAV specific processing points including request and meta-data XML associated with resources. (Network\hd_watch_network) (UNNUMBERED) (Activity - \BOLD) For each raw network read and write the VMS status code and size of the I/O is recorded. (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. (HTTP/2 - \BOLD) Provides a detailed overview of the underlying HTTP/2 framing and connection management exchanges between client and server. See (hd_http2_watch) for further detail. (Other\hd_watch_other) (UNNUMBERED) (Logging - \BOLD) Access logging events include log open, close and flush, as well as request entries. (Match - \BOLD) Shows a significant level of detail during string matching activities. May be useful during mapping, authorization and conditional processing. (Script - \BOLD) Sets CGI variable WATCH_SCRIPT allowing a script to explicitly detect this so as to output specific debugging or other information when being WATCHed. (SSL - \BOLD) If the Secure Sockets Layer image is in use this category provides a indication of high-level activity. (Internal - \BOLD) Includes information on other significant internal server processing. Examples are dictionary entries at various stages of request processing, and the high-level timing and timeout events occuring within that processing and the server in general. (Proxy\hd_watch_proxy) (UNNUMBERED) (Processing - \BOLD) Each major step during the serving of a proxied request. (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. (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. (Response Header - \BOLD) The blank-line terminated HTTP header to the response from the remote, proxied server. (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. (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. (Cache Maintenance - \BOLD) This category is not related to request processing. It allows routine and reactive cache purging activities to be watched. (Code Modules\hd_watch_codemodules)

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. (Request Filtering\hd_watch_filter)

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. (UNNUMBERED) (Protocol - \BOLD) The HTTP protocol being used to transport the request. Multiple protocols may be selected and concurrently filtered against. (Client - \BOLD) The originating host name or address. Unless server DNS host name resolution is enabled this must be expressed in dotted-decimal notation. (Service - \BOLD) 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. (Request - \BOLD) This filter operates on the entire HTTP request header. All fields supplied with the request are available to be filtered against. As this is a large, multi-line dataset filters can become quite complex and regular expression (see ([-.CONFIG]DOC_CONFIG.SDML) document, (String Matching) section) matching may be useful (see examples below). (Path/Track - \BOLD) 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 (see ([-.CONFIG]DOC_CONFIG.SDML) document, (Access Tracking) section) enter the track's unique identifier string preceded by a dollar symbol (e.g. ($ORoKJAOef8sAAAkuACc)). (Realm User - \BOLD) This filters against request authentication information. As authorization occurs relatively late in request processing some data reported earlier by WATCH will not be available. (HTTP Status - \BOLD) This allows a class of response status (1 (informational), 2 (success), 3 (redirection), 4 (client error) and 5 (server error)) or a specific response status (e.g. 200 (success), 404 (not found), 503 (service unavailable), etc.) to be filtered into the WATCH report. As this happens very late in request processing the number of reported events are limited but may provide some insight into particular processing problems.

In addition there are ((in) and (out) selectors\BOLD) against each of the filters which include or exclude the particular request based on it matching the filter.

These filters are controlled using fully-specified, wildcarded strings or using regular expression patterns (see ([-.CONFIG]DOC_CONFIG.SDML) document, (Request Processing Configuration) section). In common with all WASD processing, filter matching is case-insensitive. Of course, due to the point of application of a particular filter during request processing, some information may or may not be displayed. When a request is into or out of the report because of a matching filter a FILTER informational item is reported. (Examples\hd_watch_filter_examples) (NUMBERED) This first example shows various strings and patterns that could be applied to the client filter. alpha.example.com *.example.com 131.185.250.202 131.185.250.* (^)10.68.250.*|10.68.251.* This example various filters applied to the service (virtual server). beta.example.com:8000 beta.example.com:* http://* https:* *:80 The request filter contains the entire HTTP request header. This includes multiple, newline-delimited fields. Filtering can be simple or quite complex. These examples filter all POST requests (either in or out of the report depending on the respective selector), and all POSTs to the specified script respectively. POST * POST /cgi-bin/example*

These are the equivalent regular expressions but also will stop comparing at the end of the initial request line. The second, in this case, will also only filter against HTTP/1.1 version requests (note the final period matching the () of the () carriage control). (^^)POST .*$ (^^)POST */cgi-bin/example *HTTP/1\.1.$

This example uses a regular expression to constrain the match to a single header field (line, or newline-delimited string), matching all requests where the user agent reports using the (Gecko) browser component (Mozilla, Firefox, etc.) (^^)User-agent:.*Gecko.*$ The path and track filter. The path contains a proxied origin server request and so can be used to filter proxy requests to specific sites. /wasd_root/src/* /cgi-bin/* /web/*/cyrillic/* $ORoKJAOef8sAAAkuACc http://proxied.host.name/* The authentication filters, realm and user, can be used to select requests for a particular authenticated user, all authenticated requests or all non-authenticated requests, amongst other application. The realm field allows the authenticated user to be further narrowed as necessary. All of the following examples show only the user field with the default (in) selector set.

Authenticated requests for user DANIEL. DANIEL

All authenticated requests. %* (Report Format\hd_watch_format)

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: (SIMPLE) (time\BOLD) the event was recorded the (module\BOLD) name of the originating source code the (line\BOLD) in the code module a unique (item\BOLD) number for each thread being WATCHed event (category\BOLD) name free-form, but generally interpretable (event\BOLD) data (....................................................................) (HTML=

  WATCH Report Graphic ) (HTML/OFF)

(online graphic) (HTML/ON) (....................................................................)

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 the 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. (HTML=

HTTPd-WASD/11.0.0 OpenVMS/AXP SSL (24-FEB-2016 12:02:29.57)
HP TCPIP$IPC_SHR V5.7-ECO1 (21-MAY-2010 14:44:46.64)
OpenSSL 1.0.2f  28 Jan 2016 (30-JAN-2016 09:50:05.33) [WASD_ROOT.SRC.OPENSSL-1_0_2F.INCLUDE.OPENSSL]*.H WASD [ALPHA.EXE.SSL]SSL_LIBSSL32.OLB
$ CC (V8.3/70390009) /DECC /STAND=RELAXED_ANSI /PREFIX=ALL /OPTIMIZE /NODEBUG /WARNING=(NOINFORM,DISABLE=(PREOPTW)) /FLOAT=IEEE /IEEE=DENORM /DEFINE=(WASD_VMS_V7,SESOLA,WATCH_CAT=1,WATCH_MOD=0,WASD_ACME=1)
Digital Personal WorkStation  with 1 CPU and 1536MB running VMS V8.3 (ODS-5 enabled, VMS NAML, VMS FIB, ZLIB disabled, REGEX enabled, lksb$b_valblk[64])
$ HTTPD /PRIORITY=4 /SYSUAF=(ID,SSL)/PERSONA=RELAXED/PROFILE
AST:1983/2000 BIO:1986/2000 BYT:49966656/49999424 DIO:5000/5000 ENQ:453/500 FIL:294/300 PGFL:451216/500000 PRC:0/100 TQ:97/100
DCL Scripting: detached, as HTTP$NOBODY, PERSONA enabled
Process: WASD:80 OTHER $1$DKA0:[wasd_root.][STARTUP]STARTUP_SERVER.COM;44
$1$DKA0:[wasd_root.][LOG_SERVER]KLAATU_20160224171154.LOG;1
Instances: KLAATU::WASD:80
Watching: connect, request, req-header, response, res-header, error (603) via HTTP/2
Filter: NONE
|Time_______|Module__|Line|Item|Category__|Event...|
|01:57:59.30 WATCH    1713 0001 CONNECT    HTTP/2 with 192.168.1.2,58855 on https://wasd.*****.***,443 (0.0.0.0)|
|++++++++++++++++++++++++++++++++++++++++++
|01:57:59.30 HTTP2REQ 0235 0001 REQ-HEADER HEADER 463 bytes|
GET /httpd/-/admin/ HTTP/1.1
cache-control: max-age=0
authorization: Basic ************************
accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
upgrade-insecure-requests: 1
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36
dnt: 1
accept-encoding: gzip, deflate, sdch
accept-language: en-US,en;q=0.8
host: wasd.*****.***:443

|01:57:59.32 REQUEST  2980 0001 REQ-HEADER DATA|
ENTRY 001 [012] $ {12}request_line={28}GET /httpd/-/admin/ HTTP/1.1
ENTRY 002 [024] > {13}cache-control={9}max-age=0
ENTRY 003 [031] > {13}authorization={30}Basic ************************
ENTRY 004 [014] > {6}accept={74}text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
ENTRY 005 [010] > {25}upgrade-insecure-requests={1}1
ENTRY 006 [001] > {10}user-agent={121}Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36
ENTRY 007 [004] > {3}dnt={1}1
ENTRY 008 [018] > {15}accept-encoding={19}gzip, deflate, sdch
ENTRY 009 [007] > {15}accept-language={14}en-US,en;q=0.8
ENTRY 010 .024. > {4}host={22}wasd.*****.***:443
|01:57:59.35 SERVICE  1721 0001 CONNECT    VIRTUAL wasd.*****.***:443|
|01:57:59.35 REQUEST  3640 0001 REQUEST    GET /httpd/-/admin/|
|01:57:59.38 ADMIN    0250 0001 RESPONSE   ADMIN /httpd/-/admin/|
|01:57:59.39 NET      2308 0001 RES-HEADER DATA|
ENTRY 001 .018. $ {15}response_status={3}200
ENTRY 002 [028] < {12}x-user-agent={121}Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36
ENTRY 003 .011. < {6}server={34}HTTPd-WASD/11.0.0 OpenVMS/AXP SSL
ENTRY 004 [002] < {4}date={29}Wed, 24 Feb 2016 15:27:59 GMT
ENTRY 005 .005. < {13}accept-ranges={5}bytes
ENTRY 006 [008] < {15}accept-encoding={13}gzip, deflate
ENTRY 007 [020] < {25}strict-transport-security={16}max-age=16416000
ENTRY 008 .004. < {7}expires={29}Fri, 13 Jan 1978 14:00:00 GMT
ENTRY 009 [030] < {13}cache-control={18}no-cache, no-store
ENTRY 010 .028. < {6}pragma={8}no-cache
ENTRY 011 .030. < {12}content-type={29}text/html; charset=ISO-8859-1
ENTRY 012 [006] < {14}content-length={5}15719
|01:57:59.40 HTTP2REQ 0713 0001 RES-HEADER HEADER 497 bytes|
HTTP/1.1 200 OK
x-user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36
server: HTTPd-WASD/11.0.0 OpenVMS/AXP SSL
date: Wed, 24 Feb 2016 15:27:59 GMT
accept-ranges: bytes
accept-encoding: gzip, deflate
strict-transport-security: max-age=16416000
expires: Fri, 13 Jan 1978 14:00:00 GMT
cache-control: no-cache, no-store
pragma: no-cache
content-type: text/html; charset=ISO-8859-1
content-length: 15719

|01:57:59.41 REQUEST  1143 0001 REQUEST    STATUS 200 (OK) rx:29 tx:15809 bytes 0.109368 seconds 144,813 B/s|
|------------------------------------------
|01:58:50.58 end|

) (HTML/OFF) (Report manually wrapped for completeness.) HTTPd-WASD/11.0.0 OpenVMS/AXP SSL (24-FEB-2016 12:02:29.57) HP TCPIP$IPC_SHR V5.7-ECO1 (21-MAY-2010 14:44:46.64) OpenSSL 1.0.2f 28 Jan 2016 (30-JAN-2016 09:50:05.33) [WASD_ROOT.SRC.OPENSSL-\ 1_0_2F.INCLUDE.OPENSSL]*.H WASD [ALPHA.EXE.SSL]SSL_LIBSSL32.OLB $ CC (V8.3/70390009) /DECC /STAND=RELAXED_ANSI /PREFIX=ALL /OPTIMIZE /NODEBUG \ /WARNING=(NOINFORM,DISABLE=(PREOPTW)) /FLOAT=IEEE /IEEE=DENORM /DEFINE=(WASD_VMS_V7,SESOLA,WATCH_CAT=1,WATCH_MOD=0,WASD_ACME=1) Digital Personal WorkStation with 1 CPU and 1536MB running VMS V8.3 (ODS-5 \ enabled, VMS NAML, VMS FIB, ZLIB disabled, REGEX enabled, lksb$b_valblk[64]) $ HTTPD /PRIORITY=4 /SYSUAF=(ID,SSL)/PERSONA=RELAXED/PROFILE AST:1983/2000 BIO:1986/2000 BYT:49966656/49999424 DIO:5000/5000 ENQ:453/500 \ FIL:294/300 PGFL:451216/500000 PRC:0/100 TQ:97/100 DCL Scripting: detached, as HTTP$NOBODY, PERSONA enabled Process: WASD:80 OTHER $1$DKA0:[wasd_root.][STARTUP]STARTUP_SERVER.COM;44 $1$DKA0:[wasd_root.][LOG_SERVER]KLAATU_20160224171154.LOG;1 Instances: KLAATU::WASD:80 Watching: connect, request, req-header, response, res-header, error (603) via HTTP/2 Filter: NONE |Time_______|Module__|Line|Item|Category__|Event...| |01:57:59.30 WATCH 1713 0001 CONNECT HTTP/2 with 192.168.1.2,58855 on \ https://wasd.*****.***,443 (0.0.0.0)| |++++++++++++++++++++++++++++++++++++++++++ |01:57:59.30 HTTP2REQ 0235 0001 REQ-HEADER HEADER 463 bytes| GET /httpd/-/admin/ HTTP/1.1 cache-control: max-age=0 authorization: Basic ************************ accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8 upgrade-insecure-requests: 1 user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 \ (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36 dnt: 1 accept-encoding: gzip, deflate, sdch accept-language: en-US,en;q=0.8 host: wasd.*****.***:443 |01:57:59.32 REQUEST 2980 0001 REQ-HEADER DATA| ENTRY 001 [012] $ {12}request_line={28}GET /httpd/-/admin/ HTTP/1.1 ENTRY 002 [024] > {13}cache-control={9}max-age=0 ENTRY 003 [031] > {13}authorization={30}Basic ************************ ENTRY 004 [014] > {6}accept={74}text/html,application/xhtml+xml,\ application/xml;q=0.9,image/webp,*/*;q=0.8 ENTRY 005 [010] > {25}upgrade-insecure-requests={1}1 ENTRY 006 [001] > {10}user-agent={121}Mozilla/5.0 (Macintosh; Intel Mac OS X \ 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36 ENTRY 007 [004] > {3}dnt={1}1 ENTRY 008 [018] > {15}accept-encoding={19}gzip, deflate, sdch ENTRY 009 [007] > {15}accept-language={14}en-US,en;q=0.8 ENTRY 010 .024. > {4}host={22}wasd.*****.***:443 |01:57:59.35 SERVICE 1721 0001 CONNECT VIRTUAL wasd.*****.***:443| |01:57:59.35 REQUEST 3640 0001 REQUEST GET /httpd/-/admin/| |01:57:59.38 ADMIN 0250 0001 RESPONSE ADMIN /httpd/-/admin/| |01:57:59.39 NET 2308 0001 RES-HEADER DATA| ENTRY 001 .018. $ {15}response_status={3}200 ENTRY 002 [028] < {12}x-user-agent={121}Mozilla/5.0 (Macintosh; Intel Mac OS X \ 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36 ENTRY 003 .011. < {6}server={34}HTTPd-WASD/11.0.0 OpenVMS/AXP SSL ENTRY 004 [002] < {4}date={29}Wed, 24 Feb 2016 15:27:59 GMT ENTRY 005 .005. < {13}accept-ranges={5}bytes ENTRY 006 [008] < {15}accept-encoding={13}gzip, deflate ENTRY 007 [020] < {25}strict-transport-security={16}max-age=16416000 ENTRY 008 .004. < {7}expires={29}Fri, 13 Jan 1978 14:00:00 GMT ENTRY 009 [030] < {13}cache-control={18}no-cache, no-store ENTRY 010 .028. < {6}pragma={8}no-cache ENTRY 011 .030. < {12}content-type={29}text/html; charset=ISO-8859-1 ENTRY 012 [006] < {14}content-length={5}15719 |01:57:59.40 HTTP2REQ 0713 0001 RES-HEADER HEADER 497 bytes| HTTP/1.1 200 OK x-user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.\ 36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36 server: HTTPd-WASD/11.0.0 OpenVMS/AXP SSL date: Wed, 24 Feb 2016 15:27:59 GMT accept-ranges: bytes accept-encoding: gzip, deflate strict-transport-security: max-age=16416000 expires: Fri, 13 Jan 1978 14:00:00 GMT cache-control: no-cache, no-store pragma: no-cache content-type: text/html; charset=ISO-8859-1 content-length: 15719 |01:57:59.41 REQUEST 1143 0001 REQUEST STATUS 200 (OK) rx:29 tx:15809 \ bytes 0.109368 seconds 144,813 B/s| |------------------------------------------ |01:58:50.58 end| (HTML/ON) (Usage Suggestions\hd_watch_suggestions)

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. WATCH reports are written using non-blocking I/O into an internal buffer. This buffer is written when filled, or flushed on a one second timer. Slight latency may be experienced with sporadic WATCH report items.

(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. (Command-Line Use\hd_watch_cli)

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. (UNNUMBERED) (/NOWATCH\BOLD) Disables the use of the online WATCH facility. (/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. (UNNUMBERED) (LIST - \BOLD) The LIST keyword provides a list of all the categories (items) available for WATCHing. (NOSTARTUP - \BOLD) This keyword suppresses WATCH output until the server is ready to process requests. It must be the leading keyword. ((items) - \BOLD) A parenthesized, comma-separated list of category keywords. Available keywords can be displayed using the LIST facility. ((filters) - \BOLD) 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 (--------------------------------------------------------------------)