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. 

NOTE

---

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. 

  Username: HTTP$SERVER                      Owner:  HyperText Daemon
  Account:  HTTPD                            UIC:    [377,377] ([HTTPD,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:       512  JTquota:       1024
  Prclm:         100  DIOlm:       512  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 (see 14 - 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 NETMBX, TMPMBX, PRMMBX, PSWAPM, 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,PRMMBX,PSWAPM,SYSLCK,SYSNAM,SYSPRV,WORLD) 

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

• HTTPD$AUTH - location of the authentication/authorization configuration file

• HTTPD$CONFIG - location of the configuration file

• HTTPD$MAP - location of the mapping rule file

• HTTPD$MSG - location of the message file

• HTTPD$SERVICE - location of the optional service (virtual host) configuration file

• HTTPD$SITELOG - location of the optional plain-text site log file (see 15.4 - HTTPd Server Revise)

• HTTPD$GMT - offset from GMT (e.g. "+10:30", "-01:15"). For systems supporting DTSS (e.g. DECnet-Plus) this logical may be left undefined, with server time being calculated using the SYS$TIMEZONE_DIFFERENTIAL logical. 

• HTTPD$LOG - if logging is enabled and no log file name specified on the command line, this logical must be defined to locate the file.  When a logging period is in use this logical need only contain the directory used to store the logs. 

• HTTPD$SSL_CERT - when using the SSL executable this logical locates the default certificate. 

• HTTPD$STARTUP_SERVER... - can be used to pass parameters to HTTPd startup. 

• CGI-BIN - system logical defining a search list with the architecture-specific executable directory first, local script directory second, then the common script directory, as a concealed device. 

• HT_AUTH - directory containing authentication/authorization databases (files)

• HT_EXE - directory containing the executable images

• HT_LOGS - optional definition, for convenient log file specification

• HT_SCRATCH - location of an optional directory that scripts can use for temporary storage.  Must be read+write+delete accessable to the server account.  The HTTPD$CONFIG [DclCleanupScratchMinutesMax] directive controls whether automatic cleanup scans of this area delete any files that are older than [DclCleanupScratchMinutesOld].

• HT_SERVER_LOGS - optional definition, for convenient detached server process log file specification

The following logical name is created by the executing HTTP server and defines the name of the control mailbox:

• HTTPDport$CONTROL

The following logical names are created by the executing HTTP server if the HTTPd monitor utility is enabled:

• HTTPDport$COUNT1
• HTTPDport$COUNT2
• HTTPDport$PID
• HTTPDport$REQUEST

The server process log directory (output for the detached HTTP server processes) may require explicit access controls for the HTTPd account.  This can be done by applying an ACL similar to the following:

  $ SET SECURITY HT_ROOT:[LOG]SERVER.DIR -
    /ACL=((IDENT=HTTP$SERVER,ACCESS=R+W+E, OPTIONS=DEFAULT), -
          (IDENT=HTTP$SERVER,ACCESS=R+W+E), -
          (IDENT=*,ACCESS=NONE, OPTIONS=DEFAULT), -
          (IDENT=*,ACCESS=NONE))

As with the ACL on the server executable this can be done once, at installation (or, if right over the top, at each server startup).  Appropriate disk quotas may also need to be applied.  Also see 5.3.2.6 - Logging. 

STARTUP.COM

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

The startup uses a system batch queue.  This is the only effective way to initiate the server run-time under the server account across all VMS versions (that the author knows of anyway, RUN/DETACHED/UIC only changes the UIC).  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 a dual purpose. 

1. In a simple site setup 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. 

2. To customize the startup of a server it is recommended to copy the base STARTUP_SERVER.COM to a file in the same directory named STARTUP_SERVER_LOCAL.COM, remembering that the server account must be able to access the procedure. 

   Changes may then be made to this local copy to enable SYSUAF authentication, define job-level logicals, etc. 

3. For a site that wishes to support different services across multiple nodes in a cluster, or to support multiple HTTPd processes on the one system (each by implication having differing services, see 6.3 - Virtual Services), this procedure acts as a template for supporting these (and then is used in the same batch and detached manner described above). 

   After deciding on the organisation of nodes and/or services copy this procedure, locating the files in the same directory as STARTUP.COM, and having destination file names representing the nodes and/or ports desired.  Ensure any copies have read and execute permission for the HTTP$SERVER account! 

   • If multiple nodes in a cluster are to provide different services then create a file for each system as with the destination name being

       STARTUP_SERVER_nodename.COM
     

   • If a single system is to provide multiple services using multiple processes then the target file name must also include the identifying port number (the first in the service list), as follows

       STARTUP_SERVER_nodename_port.COM
     

   For any given system, STARTUP.COM searches for these, based on the node name, and will execute any found, one per node and/or node-port.  If none of these are found it executes the basic STARTUP_SERVER.COM, which itself should not be modified. 

   Backward-compatibility is provided for pre-v5.3 installations, with STARTUP.COM executing HT_ROOT:[HTTP$SERVER]HTTPD_BATCH.COM and HT_ROOT:[HTTP$SERVER]HTTPD80.COM if none of the above are found. 

See HT_ROOT:[EXAMPLE]STARTUP_SERVER.COM

LOGIN.COM

This procedure provides the HTTP server account login control. 

See HT_ROOT:[EXAMPLE]LOGIN.COM

5.3 - HTTPd Command Line

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

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

• /ACCEPT= comma-separated list of hosts/domains allowed to connect to the server

• /ALL[=string] has two roles.  When starting a server up assigns that server to a specific, non-default group of servers (for cluster-wide server control and proxy cache management).  When using the server control /DO= using /ALL specifies to do the action to all servers in the group. 

• /AUTHORIZATION=[SSL,ALL] the "SSL" keyword causes all authentication (both SYSUAF and HTA database) to be available only via "https:" requests.  See 14 - Secure Sockets Layer.  The "ALL" keyword forces the server to deny access to any path that does not have authorization in place against it.  See 12.1 - Authentication Policy. 

• /CGI_PREFIX= the prefix to the CGI symbol names created for a script (defaults to "WWW_", similar to the CERN VMS HTTPd, see "Scripting Environment" document)

• /DETACH= for VMS 6.2 and later this qualifier allows a DCL procedure to be specified as input to a directly detached process (in conjunction with /USER). 

• /DO= command to be performed by the executing server (see 5.3.2 - Server Command Line Control)

• /FILBUF= number of bytes in the read buffer for files open for processing (i.e. menu files, image mapping configuration files, pre-processed HTML files, etc., not direct file transfers)

• /FORMAT= overrides the configuration parameter [LogFormat]

• /REJECT= comma-separated list of hosts/domains not allowed to connect to the server

• /[NO]LOG[=name] either disables logging (overrides configuration directive), or enables logging and optionally specifies the log file name (also see section Logical Names, logging is disabled by default).  If the file specification is "SYS$OUTPUT" the server issues log entries to <stdout>, allowing user-defined log formats to be easily checked and refined. 

• /NETBUF= minimum number of bytes in the network read buffer

• /OUTBUF= number of bytes in the output buffer (for direct file transfers, buffered output from menu interpretation, HTML-preprocessing, etc.)

• /PERIOD= overrides the configuration parameter [LogPeriod]

• /PERSONA[=string] enables detached process scripting.  When used without the optional string all accounts (appropriately mapped of course) may have scripts executed under them.  If the optional string is supplied it specifies the name of a rights identifier the account must be granted before scripts can be activated under it.  See "Scripting Overview, Introduction" for further detail. 

• /PORT= overrides the configuration parameter [Port] BUT is in turn overridden by the [Service] configuration parameter and /SERVICE= qualifier (is really only useful for use with the /DO= qualifier). 

• /PRIORITY= server process priority (default is 4)

• /[NO]PROFILE allows SYSUAF-authenticated username security profiles to be used for file access (see 12.9 - SYSUAF-Authenticated Users

• /PROMISCUOUS[=password] server will accept any authentication username/password pair (used for testing, demonstrations, etc.)

• /SERVICE= comma-separated, list of server services (overrides the [Service] configuration parameter)

• /[NO]SSL[=version] controls Secure Sockets Layer protocol behaviour.  The version can be any of "2", "3" or "23" (i.e. both 2 and 3, and the default) specifying which SSL protocol version the server will service. 

• /SUBBUF= number bytes in a subprocess' SYS$OUTPUT buffer

• /[NO]SWAP controls whether the server process may be swapped out of the balance set (default is swapping disabled)

• /[NO]SYSUAF[=ID,SSL,WASD] allows or disallows (D) username authentication using the server system's SYSUAF (see 12.9 - SYSUAF-Authenticated Users, the optional "SSL" keyword causes SYSUAF authentication to be available only via "https:" requests (see 14 - Secure Sockets Layer), and the optional "ID" keyword makes SYSUAF authentication only available to account possessing a specific identifier.  See 12.9 - SYSUAF-Authenticated Users.  The "WASD" keyword make the deprecated, "hard-wired" WASD identifier environment available to this server.  See 12.9.2 - WASD "Hard-Wired" Identifiers. 

• /USER for VMS 6.2 and later this qualifier allows the /DETACH qualifier to directly create a detached process executing as the specified username. 

• /VERSION merely displays the executable's version string and the copyright notice

• /[NO]WATCH= controls the use of the WATCH reporting facility.  See 16 - WATCH Facility for further details. 

Note: buffer sizes apply on a per-request (thread) basis, and may be tailored for specific environments at server startup. 

5.3.2 - Server Command Line Control

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 /ALL qualifier (for most directives).  Of course, these commands are available from batch jobs as well as interactively.  The same functionality is available from the on-line Server Administration Menu. 

5.3.2.1 - Accounting

Server counters may be zeroed.  These counters are those visible from the statistics admininstration menu item and when using the HTTPDMON utility. 

  $ HTTPD /DO=ZERO

See 12 - 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 (see 12.8 - Authorization Cache). 

  $ HTTPD /DO=AUTH=PURGE

Server cache control may also be exercised from the server administration menu, see 15 - Server Administration.  The file cache (see 17 - 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

Server logging control may also be exercised from the server administration menu, see 15 - Server Administration. 

Open a log file. 

  $ HTTPD /DO=LOG=OPEN

Optionally open and specify a log file name.  This overrides any /LOG=file-name or HTTPD$LOG specified file name.  The /ALL qualifier is not available. 

  $ HTTPD /DO=LOG=OPEN=file-name

The log file may be closed and reopened using a different name (allowing continuous operation but, for example, with daily log files).  This overrides any /LOG=file-name or HTTPD$LOG specified file name.  The /ALL qualifier is not available. 

  $ HTTPD /DO=LOG=REOPEN=file-name

Close the log file. 

  $ HTTPD /DO=LOG=CLOSE

Unwritten log records may be flushed to the file. 

  $ HTTPD /DO=LOG=FLUSH

The format and period specification of the log may be changed (only takes effect after the next log file open/reopen).  The /ALL qualifier is not available. 

  $ HTTPD /DO=LOG=FORMAT=string
  $ HTTPD /DO=LOG=PERIOD=string

See 10 - Mapping Rules. 

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

  $ HTTPD /DO=MAP

Server shutdown may also be exercised from the server administration menu, see 15 - 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

This variant restarts the server immediately regardless of existing connections. 

  $ HTTPD /DO=RESTART=NOW