WASD VMS Hypertext Services -Technical Overview

19 - Server Administration

19.1 - Access Before Configuration
19.2 - Access Configuration
19.3 - Server Instances
19.4 - HTTPd Server Reports
19.5 - HTTPd Server Revise
19.6 - HTTPd Server Action
19.7 - HTTPd Command Line
    19.7.1 - Accounting
    19.7.2 - Authentication
    19.7.3 - Cache
    19.7.4 - DCL/Scripting Processes
    19.7.5 - DECnet Scripting Connections
    19.7.6 - Instances
    19.7.7 - Logging
    19.7.8 - Mapping
    19.7.9 - Shutdown and Restart
    19.7.10 - Secure Sockets Layer
    19.7.11 - Throttle
[next] [previous] [contents] [full-page]

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 other provide more detailed information intended for server debugging and development purposes.

[graphic]  Server Administration Graphic

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

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

Access to many portions of the package is constrained by file protections and directory listing access files. See 16.10.8 - SYSUAF Profile For Full Site Access for a method for circumventing these restrictions.


19.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 (20 - WATCH Facility). This can be done quite simply by using the authentication skeleton-key (16.11 - 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


19.2 - Access Configuration

One established the site should make the Server Administration facility a configured facility of the site. The value of its facilities cannot be overstated. The section 15.1 - SYSUAF/Identifier Authentication provides a short guide to setting up authorization for server administration purposes.

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

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

If a full authorization environment is not required but administration via browser is still desired restrict access to browsers executing on the server system itself, using an appropriate SYSUAF-authenticated username. Provision of a VMS account for server administration only is quite feasable, see 16.10.5 - Nil-Access VMS Accounts.

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

If SSL is in use (18 - Secure Sockets Layer) then username/password privacy is inherently secured via the encrypted communications. To restrict server administration functions to this secure environment add the following to the HTTPD$MAP configuration file:

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

When using the revise capability of the Server Administration facility is necessary to comply with all the requirements for Web update of files. This is discussed in general terms in 22 - HTTPd Web Update. Revision of server configuration files requires path permissions allowing write access for the username(s) doing the administration, as well as the required ACL on the target directory (in the following example HT_ROOT:[LOCAL]).

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

It is possible to allow general access to the 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 (6.5 - GZIP Encoding) 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.


19.3 - Server Instances

With a single instance (6.2 - Server Instances) access to Server Administration reports, etc. is always serviced by the one server process. If multiple instances are configured 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 (Administration Services) available from the Server Administration page.

  2. The Server Administration page (Control Section) and the command-line (19.7.6 - 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's changed to "max" allowing the HTTPD$CONFIG configuration directive [InstanceMax] to once again determine the number of instances required.

The latter approach is particularly useful when performing detailed WATCH activities (20 - 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 wasd.dsto.defence.gov.au: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 wasd.dsto.defence.gov.au:80
  Server Administration - HTTPd:80


19.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. These are listed 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 authorization (19.1 - Access Before Configuration).


19.5 - HTTPd Server Revise

The server provides a comprehensive configuration revision facility.


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 (7.5 - Scripting) this poses minimal threat to server configuration integrity.

  1. Specifically map the /ht_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 /ht_root/ ones).
      # HTTPD$MAP
      pass /ht_root/local/* auth=all
    

  2. Add appropriate authorization rules (example from 15.1 - SYSUAF/Identifier Authentication).
      # HTTPD$AUTH
      ["Web Admin"=WASD_WEBADMIN=id]
      /httpd/-/admin/* r+w
      /ht_root/local/* r+w
    

  3. Update access to the directory can be applied using the SECHAN utility (23.11 - SECHAN Utility).
      $ SECHAN /WRITE HT_ROOT:[000000]LOCAL.DIR
      $ SECHAN /WRITE HT_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 (16.10.7 - SYSUAF 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.

  # HTTPD$MAP
  set /ht_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 HT_ROOT:[000000]LOCAL.DIR
  $ SECHAN /PACKAGE HT_ROOT:[LOCAL]
  $ SECHAN /CONTROL HT_ROOT:[000000]LOCAL.DIR


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


Configuration Action Section


19.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 == "$HT_EXE:HTTPD"
 
  $ HTTPD == "$HT_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. If a non-default server port then it will be necessary to provide a /PORT= qualifier with any command.

These directives are communicated from the command-line (and Server Administration page analogue - Control Section) 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.


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


19.7.2 - Authentication

See 16 - Authentication and 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 (16.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 (19 - Server Administration).

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


19.7.3 - Cache

Server cache control may also be exercised from the Server Administration page (19 - Server Administration). The file cache (13 - Cache 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


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

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


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


19.7.6 - Instances

The number of server instances (6.2 - 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 HTTPD$CONFIG configuration directive [InstanceMax] to once again determine the number of instances required. The same functionality is available from the Server Administration page (19.6 - HTTPd Server Action).

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

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


19.7.7 - Logging

Server logging control may also be exercised from the server administration menu (19 - 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
OBSOLETE

The following directives have been rendered obsolete due to the increasing complexity of WASD access logging.
  $ HTTPD /DO=LOG=FORMAT=string
  $ HTTPD /DO=LOG=OPEN=file-name
  $ HTTPD /DO=LOG=PERIOD=string
  $ HTTPD /DO=LOG=REOPEN=file-name


19.7.8 - Mapping

See 14 - Request Processing Configuration.

The mapping rule file (HTTPD$MAP) may be reloaded using either of these variants.

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


19.7.9 - Shutdown and Restart

Server shutdown may also be exercised from the Server Administration page (19 - 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


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

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


19.7.11 - 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=USER=username
  $ HTTPD /DO=THROTTLE=TERMINATE=SCRIPT=script-path


[next] [previous] [contents] [full-page]