# WASD Features and Facilities

# 9.Server Administration

9.1 Access Before Configuration
9.2 Access Configuration
9.3 Server Instances
9.4 HTTPd Server Reports
9.5 HTTPd Server Revise
9.6 HTTPd Server Action
9.7 HTTPd Command Line
9.7.1 Accounting
9.7.2 Access Control
9.7.3 Alignment Faults
9.7.4 Authentication
9.7.5 Cache
9.7.6 Configuration Check
9.7.7 DCL/Scripting Processes
9.7.8 DECnet Scripting Connections
9.7.9 Hhelppp!
9.7.10 HTTP/2 Connection
9.7.11 Instances
9.7.12 Instance Status
9.7.13 Logging
9.7.14 Mapping
9.7.15 Network Connection
9.7.16 Shutdown and Restart
9.7.17 Secure Sockets Layer
9.7.18 Throttle
9.7.19 WebSocket

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

The online Server Administration facility provides a rich collection of functionality, including server control, reports and configuration. Some of these are intended as general administration tools while others provide more detailed information intended for server debugging and development purposes.

The administration interface also provides some basic server statistics in the lower right panel; local date/time, internet (UTC) equivalent, client host, connection protocol, and request RTT (the essential network overhead between client and server), up-times for system, server process, server executable, CPU consumed by it, along with current connection and requests-in-progress statistics. Alerts (in red) also can appear in this panel.

The value of the WATCH facility 10. WATCH Facility as a general configuration and problem-solving tool cannot be overstated.

All server configuration files, with the exception of the authentication databases, are plain text and may be modified with any prefered editor. However the majority of these can also be administered online through a browser. In addition the update facility allows some administration of file system portions of the Web. See 12. HTTPd Web Update.

Access to many portions of the package is constrained by file protections and directory listing access files. See for a method for circumventing these restrictions.

## 9.1 Access Before Configuration

It is often a significant advantage for the inexperienced administrator on a new and largely unconfigured installation to be able to gain access to the facilities offered by Server Administration, particularly the WATCH facility (10. WATCH Facility). This can be done quite simply by using the authentication skeleton-key (3.12 Skeleton-Key Authentication). This allows the site administrator to register a username and password from the command-line that can be used to gain access to the server. In addition, the server ensures that requesting an otherwise non-authorized Server Administration facility generates a challenge which invokes a username/password dialog at the browser allowing the user to enter the previously registered username and password and gain access.

##### Method

- Register the skeleton-key username and password.
  $ HTTPD == "$WASD_EXE:HTTPD_SSL.EXE" $! HTTPD == "$WASD_EXE:HTTPD.EXE" $ HTTPD /DO=AUTH=SKELKEY=__username:password

  Note that the username must begin with two underscores, be at least 6 characters, is delimited by a colon, and that the password must be at least 8 characters. By default this username and password remains valid for 60 minutes. Choose strings that are less-than-obvious!

- Access the server via a browser and use the server Server Administration facility.

  https://the.host.name:port/httpd/-/admin/

- After use the skeleton-key may be explicitly cancelled if desired.
  $ HTTPD /DO=AUTH=SKELKEY=0

## 9.2 Access Configuration

Once established the site should make the Server Administration facility a configured facility of the site. The value of its facilities cannot be overstated.

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

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

If SSL is in use (4. Transport Layer Security) 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 WASD_CONFIG_MAP configuration file:

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

When using the revise capability of the Server Administration facility it is necessary to comply with all the requirements for Web update of files. This is discussed in general terms in 12. 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 WASD_ROOT:[LOCAL]).

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

It is possible to allow general access to the Server Administration facility 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

When GZIP compression is configured for the server (see GZIP Encoding of WASD Configuration) it is not by default applied to Server Admin reports or other pages. It can be applied, selectively if desired, using mapping rules. For instance, to apply it to all requests not from the local intranet a rule similar to the following can be added before the Server Admin path mapping itself.

if (!remote-addr:192.168.0.0/8) set /httpd/-/admin/* response=GZIP=all pass /httpd/-/admin/* /httpd/-/admin/*

GZIP content-encoding can never be applied to WATCH reports.

## 9.3 Server Instances

With a single instance (see 8.1 Server Instances) access to Server Administration reports, etc. is always serviced by the one server process. If multiple instances are configured then in common with all requests administration requests will be serviced by any one of the associated processes depending on the momentary state of the round-robin distribution.

There are many circumstances where it is preferable to access only the one server. This can be accomplished for two differing objectives.

1. To facilitate access to a specific instance's Server Administration page, including instance-specific reports etc. This is provided through the use of an administration service port (see Administration Services of WASD Configuration) available from the Server Administration page.
2. The Server Administration page (‘Control Section’ in 9.6 HTTPd Server Action) and the command-line 9.7.11 Instances) provides the capability to explicitly set the number of instances supported, overriding any configuration directive. After explicitly setting this, using either means, the server must be restarted. The explicit startup setting remains in effect until it is changed to "max" allowing the WASD_CONFIG_GLOBAL configuration directive [InstanceMax] to once again determine the number of instances required.

The latter approach is particularly useful when performing detailed WATCH activities (10. WATCH Facility).

When multiple per-node instances are executing the Server Administration pages and reports all include an indication of which process serviced the request. When accessing no instance in particular the process name is presented in parentheses after the page title

HTTPd www.example.com:80 Server Administration (HTTPd:80)
When a particular instance's administration service port is being used the process name is separated from the page title by a hyphen
HTTPd www.example.com:80 Server Administration - HTTPd:80

Multi-instance status (see 8.1.4 Status) snapshots are available via HTTPDMON, the Server Admin main page and can be reported from the command line using

$ HTTPD /DO=STATUS

## 9.4 HTTPd Server Reports

The server provides a number of internally generated reports. Some of these are of general interest. Others are more for evaluating WASD behaviour and performance for development purposes. Appropriate reports have a refresh selector allowing the report to be updated at the selected period. The following list is in the approximate order in which they occur top-to-bottom, left-to-right in the menu layout.

It is possible to use this facility standalone, without configuring authorisation (9.1 Access Before Configuration).

- 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.
- Log ∇ ϟ ⁞⁞ – Display the server process (SYS$OUTPUT) log in four variants. The Log in Log∇ ϟ ⁞⁞ displays the raw server log, the ∇ in Log∇ϟ ⁞⁞ lists the log with all noticed filtered out, the ϟ in Log ∇ϟ⁞⁞ list only the noticed, and the ⁞⁞ in Log ∇ ϟ⁞⁞ a list of files in the server log directory.
- Configuration – A tabular summary of the server's current configuration. This is a convenient method for viewing the information from the WASD_CONFIG_GLOBAL file.
- Services – A tabular report listing the current services (virtual servers) and the service-specific parameters.
- Messages – A tabular report of the server's current message database, multiple languages shown if configured that way.
- 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.
- Path Authorization – If authorization is in use (3. Authentication and Authorization) this report lists the paths with associated authorization and access control.
- 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.
- Access Control – These reports list both Accept Rules and Reject Rules, current IP rejection list, and log of rejections derived from the current server log.
- Secure Sockets – 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. Other reports allow the Certificate Authority (CA) database to be view and edited, if available due to X.509 authentication being enabled.
- AlnFlt – Memory access alignment faults are constantly monitored. This displays the accumulated statistics since the most recent startup. Should always be zero! Does not apply to x86-64.
- Cache – Allows monitoring of cache behaviour and performance, as well as the files currently in the cache (see Cache Configuration of WASD Configuration).
- Cluster – For clustered systems generates a report similar to the System Report but with a cluster emphasis.
- 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).

  Process information shows how many actual processes 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 processes may actually exist at any one time (the margin allows for process deletion latency). A count of how many times the CGIplus processes 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 process life-time (in minutes, zero implying indefinite), the number purged due to life-time expiry and the number of CGIplus processes that the server has actually purged (deleted) to maintain the soft-limit margin specified above.

  Each of the allocated process 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 process existing. This can be a zombie process or a CGIplus process. If no process is indicated then the other information represents the state the last time the item's associated process 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 process 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 process is currently in use the client information show the client host name.

  If any processes are associated with any data structure a purge button is provided that forces all processes 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 process deletion occurs when that processing is complete. The purge button does not force a process to delete, so a second button forces all processes to delete immediately. This can be used to forceably clear errant scripts, etc., but be warned script processing is indiscrimately stopped!

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

- HTTP – Reports HTTP/2 and HTTP/1.n statistics together as well as providing a list of current HTTP/2 connections with some per-connection data. See 5. HTTP/2 for details.
- Lock – Lists the names and status of all lock resources used to manage single and multiple instances across single systems or a cluster. This report is more relevant for evaluating and debugging WASD behaviour.
- Match – To assist with the refinement of string matching patterns (see String Matching of WASD Configuration). This report allows the input of target and match strings and allows direct access to the server's wildcard and regular expression matching routines. Successful matches show the matching elements and a substitution field allows resultant strings to be assessed.
- Memory+ – Provides a report and does an integrity check on each of the Virtual Memory (VM) zones employed by the WASD HTTPd. The plus displays all server process memory zones. Just click on the + in Memory+.
- 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.
- 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.
- Request+ – Lists in-progress requests (always shows at least your own connection accessing this report :-) Additional buttons after the report allow selection of a report that in addition displays current persistent network connections, requests currently under throttle control, and if enabled a list (history) of the most recent requests (enabled by the configuration parameter [RequestHistory]). Current requests may be selected for one-shot WATCH-processing reports from this page ().

  The plus displays a consolidated Request & Connection + History Report. Just click on the + in Request+.

  Two other diagnostic tools are available from the same link. The first, WATCH-peek Report, providing a snapshot of 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 accesses the "peek" internals plus a one-shot WATCH-processing report.

  For servers handling a great quantity of concurrent traffic this can generate a very large report. The Supervisor report can also provide a profile of the servers current load.

- System+ – Shows the system, all users, memory and CPU status as a single report.

  ###### Server CLI /SYSPLUS

  ##### System Report PLUS

  The standard system report uses a scripting process to present some of this data in familiar formats (using DCL commands). If the system is faltering for some reason (e.g. resource exhaustion) this may not be possible – and just when it might be really useful! It may still be possible to gain some insight into system status using the system+ report. This uses only internal code and provides significant technical data on system, cluster, device and process status. Just click on the + in System+. It can also be considered an alternate or supplementary view of the system for those that don't mind, or who thrive on, more technical content.

  $ HTTPD /SYSPLUS can provide the same report data at the command-line for circumstances where the server is unresponsive but an interactive session is available. Requires a 132 character width terminal session. The /SYSPLUS report generator may be used with /OUTPUT=<filename> to capture and store report data. See Server Image Command-Line Parameters of WASD Configuration).

- Throttle – This report provides a list of paths with throttle rules mapped against them. It provides the throttle values along with current and history activity counters.
- WATCH – This report provides an online, real-time, in-browser-window view of request processing on the running server. See 10. WATCH Facility for details.
- WebDAV – Provides configuration and statistics.
- WebSocket – Lists in-progress WebSocket requests with connection statistics and the scripting process associated with.
- Activity – Provide a graphical snapshot of server activity of a given period.

  The statistics are stored in a permanent global section and so carry-over between server restarts. Where multiple instances are executing the data represents an accumulation of all instances' processing. It is enabled by the configuration parameter [ActivityDays]. The Server Administration facility 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 by a line graph. A bar across the column of the request histogram indicates the peak number of concurrent requests during the period. A greyed area indicates no data available for that time (i.e. before the latest server startup, or in the future).

  Server startup and shutdown events are indicated by solid, vertical lines the full height of the graph (see example for a restart event).

  - startup - green
  - shutdown - black
  - restart - grey
  - error exit - red

  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.

  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.

  For multiple hour reports 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.

## 9.5 HTTPd Server Revise

The server provides a comprehensive configuration revision facility.

- Configuration – 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 – 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 – 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 (9.6 HTTPd Server Action).
- 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 (9.6 HTTPd Server Action).
- 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 (9.6 HTTPd Server Action).
- 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

  3. Authentication and Authorization covers authentication detail.

- 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 the logical name WASD_SITELOG.

- Access Control – These allows both Accept Rules and Reject Rules to be independently edited, then reloaded from the menu.

##### Enabling 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.

1. 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
2. Add appropriate authorization rules (example from Authorization Configuration (Basics) of WASD Configuration).
   # WASD_CONFIG_AUTH ["Web Admin"=WASD_WEBADMIN=id] /httpd/-/admin/* r+w /wasd_root/local/* r+w
3. Update access to the directory can be applied using the SECHAN utility (13.12 SECHAN Utility).
   $ SECHAN /WRITE WASD_ROOT:[000000]LOCAL.DIR $ SECHAN /WRITE WASD_ROOT:[LOCAL]
4. Load the new mapping and authorization rules.
   $ HTTPD /DO=MAP $ HTTPD /DO=AUTH=LOAD

##### Alternative Using /PROFILE

If a site is using SYSUAF authentication and security profiles enabled using the /PROFILE startup qualifier (13.12 SECHAN Utility) 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

## 9.6 HTTPd 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 9.7 HTTPd Command Line.

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

- Server Restart/restartNOW/restartQuiet/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. 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 – The WASD_CONFIG_LOG logical must be configured to allow access logging to be enabled and disabled from this menu.
- 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.
- Instance Startup – 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 – Provides a on-line facility parallel to that provided by the command-line /DO qualifier (9.7 HTTPd Command Line). 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

- Statistics Zeroed – All counters are zeroed (except the number-of-times-zeroed counter!)
- 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.

- Path Authorization Reload – Reloads the path authorization directives from the on-disk file into the running server.
- 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.
- Access Control – This allows Accept Rules and Reject Rules to be jointly reloaded. It also allows the IP Rejection list to be purged.

## 9.7 HTTPd Command Line

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, is available to the privileged user.

These directives are communicated from the command-line (and Server Administration page analogue - ‘Control Section’ in 9.6 HTTPd Server Action) 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

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?

Can't quite remember what it can (and by implication can't) do?

$ HTTPD /DO=HELP

##### Server Log Annotation

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="<string>" 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.

### 9.7.1 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.

### 9.7.2 Access Control

Server access via the WASD_CONFIG_ACCEPT and WASD_CONFIG_REJECT configuration files can reloaded and the IP reject list purged (cleared) using the following commands.

$ HTTPD /DO=ACCEPT $ HTTPD /DO=REJECT $ HTTPD /DO=REJECT=PURGE

### 9.7.3 Alignment Faults

Does not apply to x86-64.

Alignment faults can be a significant performance issue and considerable effort has been invested in completely eliminating them. This was done using an 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

### 9.7.4 Authentication

See 3. Authentication and Authorization.

The authorization rule file (WASD_CONFIG_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 (3.9 Authorization Cache).

$ HTTPD /DO=AUTH=PURGE

A "skeleton-key" username and password may be entered, amongst things allowing access to the Server Administration facility (9. Server Administration).

$ HTTPD /DO=AUTH=SKELKEY=_<username>:<password>[:<period>]

### 9.7.5 Cache

Server cache control may also be exercised from the Server Administration page (9. Server Administration). The file cache (see Cache Configuration of WASD Configuration) 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

### 9.7.6 Configuration 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

### 9.7.7 DCL/Scripting Processes

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

A more selective DELETE and PURGE is possible, where user name, script name, or script file name is 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

When using the proctor facility (Script Proctor in WASD Scripting) revised rules in WASD_CONFIG_GLOBAL may be applied to the running server (proctored scripting processes created and deleted), or merely loaded into the server ruleset (requiring subsequent DCL=PURGE or DCL=DELETE to activate).

$ HTTPD /DO=DCL=PROCTOR=APPLY $ HTTPD /DO=DCL=PROCTOR=LOAD

### 9.7.8 DECnet Scripting Connections

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

### 9.7.9 Hhelppp!

$ HTTPD /DO=HELP o ALIGN= START, STOP, ZERO with [<buf-size>,<items>,<mask>] 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 $

### 9.7.10 HTTP/2 Connection

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

### 9.7.11 Instances

The number of server instances (see 8.1 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, 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 (9.6 HTTPd Server Action).

There are also directives to assist with WATCH activities (8.1 Server Instances).

$ HTTPD /DO=INSTANCE=PASSIVE $ HTTPD /DO=INSTANCE=ACTIVE

### 9.7.12 Instance Status

Multi-instance (see 8.1 Server Instances) status (see 8.1.4 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

### 9.7.13 Logging

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

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

### 9.7.14 Mapping

See Request Processing Configuration of WASD Configuration.

The mapping rule file (WASD_CONFIG_MAP) may be reloaded using either of these variants.

$ HTTPD /DO=MAP $ HTTPD /DO=MAP=LOAD

### 9.7.15 Network Connection

Current network connections can be listed at the CLI.

$ HTTPD /DO=NET=LIST

This can display in an 80 character terminal depending on column widths (e.g. service and client names) but in some circumstances will require 132 characters to use effectively. The CLI command requests the running server to generate a report and return that via the $BRKTHRU service.

Note that with HTTP/1.n there is a one-to-one relationship between requests in progress and a network connection, displayed as a single integer, e.g. 1651. With HTTP/2 there can be a many to one, where listed "connections" being processed (i.e. requests in progress) are virtual connections being transported by an independent actual connection, and displayed as 1639->1632, where ->1632 is the actual connection.

Connect Service / Request Client Time Duration ---------- ------------------- ---------------- -------- -------- 1651 https:wasd.lan:4443 router.lan,56314 08:05:02 6.636s [persistent:4] 1639->1632 https:wasd.lan:443 router.lan,56310 08:00:52 4.147s GET /httpd/-/admin/report/WATCH?rqp=1&rsp=1&con=1&err=1&htp=i&cl... 1626->1606 https:wasd.lan:443 router.lan,56267 07:59:57 00:10:45 GET /cgi-bin/smonitor?classes=&MODES=2&PROCESSES=3&SYSTEM=1&inte... ->1632 https:wasd.lan:443 router.lan,56310 08:00:36 19.88s current:1 peak:1 count:5 ->1606 https:wasd.lan:443 router.lan,53267 07:25:41 00:35:14 current:1 peak:4 count:13 1 HTTP/1.n, 2 via HTTP/2, 2 HTTP/2, 17-SEP-2021 07:58:17

Disconnect idle (persistent HTTP/1.n and HTTP/2) connections.

$ HTTPD /DO=NET=PURGE

All network connections can be disconnected (this may cause clients to lose data), selectively idle HTTP/1.n or HTTP/2 connections, a specific connection number and those matching the specified URI.

$ HTTPD /DO=NET=PURGE=ALL $ HTTPD /DO=NET=PURGE=HTTP1 $ HTTPD /DO=NET=PURGE=HTTP2 $ 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

### 9.7.16 Shutdown and Restart

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

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 :-)"

### 9.7.17 Secure Sockets Layer

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 []:

### 9.7.18 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

### 9.7.19 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

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎