WASD Hypertext Services - Technical Overview

5 - Server Account and Environment

5.1 - VMS Server Account
5.2 - VMS Scripting Account
5.3 - Account Support Files
5.4 - Other Resources
5.5 - HTTPd Command Line
    5.5.1 - Server Startup
    5.5.2 - Server Command Line Control
        5.5.2.1 - Accounting
        5.5.2.2 - Authentication
        5.5.2.3 - Cache
        5.5.2.4 - DCL/Scripting Subprocesses
        5.5.2.5 - DECnet Scripting Connections
        5.5.2.6 - Instances
        5.5.2.7 - Logging
        5.5.2.8 - Mapping
        5.5.2.9 - Shutdown and Restart
        5.5.2.10 - Secure Sockets Layer
        5.5.2.11 - Throttle
[next] [previous] [contents] [full-page]

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:

A general rule is more is better, after all, it will only use as much as it needs! To assist with setting a reasonable BYTLM quota the WATCH report provides some feedback on server BYTLM usage. See 19 - WATCH Facility for further details.
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.


5.1 - VMS Server Account

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


5.2 - VMS Scripting Account

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


5.3 - Account Support Files

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


HTTPd Executables

Two server executables can be built by the package.


Privileged Image

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, 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,PRMGBL,PRMMBX,PSWAPM,SHMEM,-
                SYSGBL,SYSLCK,SYSNAM,SYSPRV,WORLD) 


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

  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!

    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


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


5.5 - HTTPd Command Line

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.


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


5.5.2.2 - Authentication

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


5.5.2.3 - Cache

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


5.5.2.4 - DCL/Scripting Subprocesses

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


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


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


5.5.2.8 - Mapping

See 13 - Mapping Rules.

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

  $ HTTPD /DO=MAP


5.5.2.9 - Shutdown and Restart

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


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

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


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


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