WASD Hypertext Services - Technical Overview

The HTTP server account should be a standard account, preferably in a group of its own (definitely at least a non-system, non-user group), with sufficient quotas to handle the expected traffic.

Process Quotas!

---

Server process quotas must be sufficient to support the expected traffic load. In particlular PRCLM must support expected script usage. BYTLM, BIOLM, DIOL, FILLM and PGFLQUO are all significant considerations.

---

Symptoms of insufficient process quotas include:

• Textual pages OK, but pages with a significant number of images having some or all "broken".

• Scripts failing mysteriously, particularly when multiple in use concurrently.

• Server and associated scripts all apparently waiting MWAIT or RWAST states.

TCP/IP Agent Resources!

---

On an associated topic; some TCP/IP agents require particular internal resources to be adjusted against given loads (e.g. buffer space allocations). Symptoms of resource starvation may be TCP/IP services, including WASD, "pausing" for significant periods or associated processes entering miscellaneous wait states, etc., during processing. Please ensure such TCP/IP agents are appropriately dimensioned for expected loads.

---

The following provides a guide to the account.

  Username: HTTP$SERVER                      Owner:  WASD Server
  Account:  HTTPD                            UIC:    [077,001] ([HTTP$SERVER])
  CLI:      DCL                              Tables: DCLTABLES
  Default:  HT_ROOT:[HTTP$SERVER]
  LGICMD:   LOGIN
  Flags:  Restricted DisNewMail
  Primary days:   Mon Tue Wed Thu Fri
  Secondary days:                     Sat Sun
  Primary   000000000011111111112222  Secondary 000000000011111111112222
  Day Hours 012345678901234567890123  Day Hours 012345678901234567890123
  Network:  ##### Full access ######            ##### Full access ######
  Batch:    ##### Full access ######            ##### Full access ######
  Local:    -----  No access  ------            -----  No access  ------
  Dialup:   -----  No access  ------            -----  No access  ------
  Remote:   -----  No access  ------            -----  No access  ------
  Expiration:            (none)    Pwdminimum:  6   Login Fails:     0
  Pwdlifetime:         90 00:00    Pwdchange:      (pre-expired)
  Last Login:            (none) (interactive), 11-MAY-1995 08:44 (non-interactive)
  Maxjobs:         0  Fillm:       300  Bytlm:       500000
  Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0
  Maxdetach:       0  BIOlm:      2048  JTquota:       1024
  Prclm:         100  DIOlm:      1024  WSdef:         1000
  Prio:            4  ASTlm:      2000  WSquo:         5000
  Queprio:         0  TQElm:       100  WSextent:     20000
  CPU:        (none)  Enqlm:       256  Pgflquo:     500000
  Authorized Privileges:
    NETMBX    TMPMBX
  Default Privileges:
    NETMBX    TMPMBX

The following provides a guide to the account.

  Username: HTTP$NOBODY                      Owner:  WASD Scripting
  Account:  HTTPD                            UIC:    [076,001] ([HTTP$NOBODY])
  CLI:      DCL                              Tables: DCLTABLES
  Default:  HT_ROOT:[HTTP$NOBODY]
  LGICMD:   LOGIN
  Flags:  Restricted DisNewMail
  Primary days:   Mon Tue Wed Thu Fri
  Secondary days:                     Sat Sun
  Primary   000000000011111111112222  Secondary 000000000011111111112222
  Day Hours 012345678901234567890123  Day Hours 012345678901234567890123
  Network:  ##### Full access ######            ##### Full access ######
  Batch:    ##### Full access ######            ##### Full access ######
  Local:    -----  No access  ------            -----  No access  ------
  Dialup:   -----  No access  ------            -----  No access  ------
  Remote:   -----  No access  ------            -----  No access  ------
  Expiration:            (none)    Pwdminimum:  6   Login Fails:     0
  Pwdlifetime:         90 00:00    Pwdchange:      (pre-expired)
  Last Login:            (none) (interactive), 11-MAY-1995 08:44 (non-interactive)
  Maxjobs:         0  Fillm:       300  Bytlm:       500000
  Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0
  Maxdetach:       0  BIOlm:      2048  JTquota:       1024
  Prclm:         100  DIOlm:      1024  WSdef:         1000
  Prio:            4  ASTlm:      2000  WSquo:         5000
  Queprio:         0  TQElm:       100  WSextent:     20000
  CPU:        (none)  Enqlm:       256  Pgflquo:     500000
  Authorized Privileges:
    NETMBX    TMPMBX
  Default Privileges:
    NETMBX    TMPMBX

NOTE

---

Support procedures often change between versions. It is always advisable to check the versions documentation before installing or updating. Examples may be found in HT_ROOT:[EXAMPLE].

---

Two server executables can be built by the package.

• HTTPD.EXE - basic server

• HTTPD_SSL.EXE - SSL-enabled server (17 - Secure Sockets Layer).

As this image is to be installed with privileges unauthorized use should be prevented by applying an ACL similar to the following against the executable image:

  $ SET SECURITY HT_EXE:HTTPD.EXE -
    /ACL=((IDENT=HTTP$SERVER,ACCESS=R+E),(IDENT=*,ACCESS=NONE))

This can be done once, at installation, or for peace-of-mind (a.k.a. VMS-ish paranoia) at each server startup.

As the HTTP$SERVER account should be completely unprivileged, and the HTTPd image requires CMKRNL, NETMBX, TMPMBX, PRMGBL, PRMMBX, PSWAPM, SHMEM (VAX only), SYSGBL, SYSLCK, SYSNAM, SYSPRV and WORLD privileges (see the "Nuts and Bolts" document for a description of how and why the server uses these privileges). It must be installed using a command similar to the following:

  $ INSTALL = "$SYS$SYSTEM:INSTALL/COMMAND_MODE"
  $ INSTALL ADD HT_EXE:HTTPD.EXE -
    /PRIVILEGE=(ALTPRI,CMKRNL, PRMGBL,PRMMBX,PSWAPM,SHMEM,-
                SYSGBL,SYSLCK,SYSNAM,SYSPRV,WORLD) 

Putting all this together the HTTP server startup procedure becomes something similar to the supplied example. It should be called from SYSTARTUP_VMS.COM or the site's equivalent.

This procedure will support simple and quite complex sites. It works closely with STARTUP_SERVER.COM (see below). It is designed to accept parameters from the command-line or as pre-assigned symbols. Operating in this fashion should mean that no modifications will need to be made to the procedure itself. Startup characteristics are essentially determined by DCL symbol values. Some symbols are booleans, switching functionality off and on, others require string values. When relevant startup values are not assigned a reasonable default will be applied. See the following examples.

Startup characteristics can be determined by supplying symbol assignment values as command-line parameters when calling the procedure.

  $ @$1$DKA0:[HT_ROOT.LOCAL]STARTUP WASD_DECNET=1 WASD_SSL=1 -
  WASD_SSL_CERTIFICATE="HT_ROOT:[LOCAL]ALPHA.PEM"

Startup characteristics can also be determined by assigning the symbol values before calling the procedure itself.

  $ WASD_DECNET = 1
  $ WASD_SSL = 1
  $ WASD_SSL_CERTIFICATE = "HT_ROOT:[LOCAL]ALPHA.PEM"
  $ @$1$DKA0:[HT_ROOT.LOCAL]STARTUP

On version of VAX VMS prior to 6.2 the startup uses a system batch queue. By default SYS$BATCH is used. If a node does not have a SYS$BATCH then one must be created. If a clustered node's SYS$BATCH is configured to run on a cluster-common batch queue (i.e. not necessarily on the startup node) then a node-specific queue must be specified.

  $ @$1$DKA0:[HT_ROOT.LOCAL]STARTUP WASD_DECNET=1 WASD_BATCH_QUEUE=THIS$BATCH

Check the procedure itself for detail on symbol names and functionality.

See HT_ROOT:[EXAMPLE]STARTUP.COM

STARTUP_LOCAL.COM

This file is automatically executed by the STARTUP.COM procedure immediately before the server is actually started. It is provided to supply all the local site's additional startup requirements. Place site-specific server environment startup in here, leaving STARTUP.COM alone as much as possible.

See HT_ROOT:[EXAMPLE]STARTUP_LOCAL.COM

STARTUP_SERVER.COM

This procedure serves two purposes.

1. Server startup:
   • If on VAX VMS V6.2 or earlier it is submitted to the SYS$BATCH queue during startup. The batch portion creates a detached process, which then again uses this procedure as input, supporting the executing HTTPd.

   • With more modern versions and architectures of VMS the procedure becomes SYS$COMMAND for a detached process created directly during the execution of STARTUP.COM.

2. The procedure then controls the activation of the HTTPd executable image during normal restarts and exits, and exits after fatal server error.

See HT_ROOT:[EXAMPLE]STARTUP_SERVER.COM

5.4 - Other Resources

Other resources required or consumed by the package.

Global Pages/Sections

Accounting and request data made available to the server monitor utility (HTTPDMON) is provided by shared global memory. This requires one global section (SYSGEN parameter GBLSECTIONS) and 16 global pages (SYSGEN parameter GBLPAGES). The activity statistics available from the Server Admininistration facility requires one global section and 816 global pages. These two global sections are permanent.

If multiple server instances are to be employed one more global section is required for a standard server (a shared authentication cache), or two more for an SSL server (a shared session cache), with another if reverse proxy verify is enabled, plus a variable number (some tens) of global pages. These global sections are temporary.

If there are insufficient global sections or pages the server will fail to start for all requirements except the activity statistics, this will just be disabled. Startup messages advise on current usage.

As permanent, system-accessable global sections are deployed it may be necessary to explicitly delete them after ad hoc server experimentation, etc. (5.5.1 - Server Startup). The startup qualifier /GBLSEC=NOPERM disables the creation of permanent global sections eliminating this requirement.

Logical Names

The following logical names are used in the operation of the HTTPd server and most must be defined before startup (system-wide, or in the job table if server-specific). These are usually created by STARTUP.COM during server startup.

Command-line qualifiers provide some server startup control as well as server runtime control.

5.5.1 - Server Startup

When starting up the server several characteristics of the server may be specified using qualifiers on the command line. If not specified appropriate defaults are employed. For recommended methods of passing parameters to the executable at server startup see STARTUP_SERVER.COM.

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.

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. The same functionality is available from the online Server Administration facility.

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

See 15 - Authentication and Authorization.

The authorization rule file (HTTP$AUTH) may be reloaded.

  $ 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 (15.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 (18 - Server Administration).

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

Server cache control may also be exercised from the Server Administration page (18 - Server Administration). The file cache (20 - Cache) may be enabled, disabled and have it's contents purged (declared invalid and reloaded) using

  $ HTTPD /DO=CACHE=ON
  $ HTTPD /DO=CACHE=OFF
  $ HTTPD /DO=CACHE=PURGE

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 subprocesses, 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 subprocesses and mark busy ones for deletion when completed processing.

  $ HTTPD /DO=DCL=PURGE

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

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 (18.6 - HTTPd Server Action).

5.5.2.7 - Logging

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

---

See 13 - Mapping Rules.

The mapping rule file (HTTPD$MAP) may be reloaded.

  $ HTTPD /DO=MAP

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

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 its resulting prompt. When entered the password is not echoed.

  $ HTTPD /DO=SSL=KEY=PASSWORD
  Enter private key password []:

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