WASD VMS 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 - Server Startup
[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 20 - 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:      5000000
  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 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) 


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

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

  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

It is recommended to pass server startup command-line parameters using the HTTPD$SERVER_STARTUP logical name that this procedure checks for and uses if present. If this is defined in the system table it's contents are applied to the server image when executed. It can be explicitly defined before WASD startup.

  $ DEFINE /SYSTEM /EXECUTIVE HTTPD$STARTUP_SERVER "/SYSUAF=ID"
  $ @$1$DKA0:[HT_ROOT.LOCAL]STARTUP

It's value can also be passed to the main startup procedure in a symbol. The startup procedure then defines a system logical name with that value (note that any quotes used must be escaped).

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

It can also be manually redefined at any time and the server restarted to apply different startup parameters to the running server.

  $ DEFINE /SYSTEM /EXECUTIVE HTTPD$STARTUP_SERVER "/SYSUAF=(SSL,ID)"
  $ HTTPD /DO=RESTART=NOW


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

Package Logical Names
Logical NameDescription
HTTPD$AUTHLocation of the authentication/authorization configuration file.
HTTPD$CONFIGLocation of the configuration file.
HTTPD$MAPLocation of the mapping rule file.
HTTPD$MSGLocation of the message file.
HTTPD$SERVICELocation of the optional service (virtual host) configuration file.
HTTPD$SITELOGLocation of the optional plain-text site log file (19.5 - HTTPd Server Revise).
HTTPD$GMTOffset 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$LOGIf 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_CERTWhen using the SSL executable this logical locates the default certificate.
HTTPD$STARTUP_SERVERCan be used to pass parameters to the server image startup command line.
AXP_BINDirectory containing Alpha script executables.
CGI-BINSystem 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.
CGI_BINDirectory containing archtecture-neutral script files.
CGI_EXEDirectory containing architecture-specific script executables.
HT_AXPDirectory containing Alpha executable images.
HT_AUTHDirectory containing authentication/authorization databases (files).
HT_EXEDirectory containing the executable images.
HT_IA64Directory containing Itanium executable images.
HT_LOGSOptional definition, for convenient log file specification.
HT_SCRATCHLocation 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_LOGSOptional definition, for convenient detached server process log file specification.
HT_VAXDirectory containing VAX executable images.
IA64_BINDirectory containing Itanium script executables.
VAX_BINDirectory containing VAX script executables.


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

Server Image Command-Line Parameters
Parameter/QualifierDescription
/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 (18 - Secure Sockets Layer). The "ALL" keyword forces the server to deny access to any path that does not have authorization in place against it (16.2 - 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).
/CLUSTERApply control /DO= to all instances in the cluster (default is to per-node instances only).
/DEMOPlaces the server into demonstration mode designed to allow full package capabilities to be demonstrated. Used by the [INSTALL]DEMO.COM procedure.
/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 (19.7 - HTTPd Command Line).
/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].
/GBLSEC=DELETEAllows a monitor-associated permanent global section to be explicitly deleted. When a server starts it creates system-accessable, permanent global sections in which to store accounting and request data. As this is permanent it would be possible for a site, perhaps experimenting with servers over a range of ports, to consume significant amounts of global pages and sections. This qualifier allows such sections to be deleted. See also the /GBLSEC=NOPERM described immediately below.
/GBLSEC=NOPERMDisables the creation of permanent global sections. They are automatically deleted when the server image exits.
/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.
/NOMONITORAllows the update of the data read by HTTPDMON to be disabled.
/NETBUF=Minimum number of bytes in the network read buffer.
/NETWORKRun the server and any scripting processes as NETWORK mode rather than the default detached OTHER mode.
/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[=ident-name,
RELAXED,AUTHORIZED,
RELAXED=AUTHORIZED]
Enables detached process scripting. When used without the ident-name all non-privileged accounts (appropriately mapped of course) may have scripts executed under them. If the optional ident-name is supplied it specifies the name of a rights identifier the account must be granted before scripts can be activated under it. The RELAXED, AUTHORIZED and RELAXED=AUTHORIZED further control the use of persona functionality with privileged accounts. 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]PROFILEAllows SYSUAF-authenticated username security profiles to be used for file access (16.10 - SYSUAF-Authenticated Users).
/PROMISCUOUS[=password]Server will accept any authentication username/password pair (used for testing, demonstrations, etc.)
/PROXY=stringAllows proxy maintainance activitied to be executed from the command line (e.g. from batch jobs, etc.). See 17.2.3 - Cache Management.
/SCRIPT=AS=Specifies the username of the default scripting account.
/SERVICE=Comma-separated, list of server services (overrides the [Service] configuration parameter).
/SOFTWARE=An arbitrary string that can be used to override the server software identification (i.e. "HTTPd-WASD/9.0.0 OpenVMS/AXP SSL").
/[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 (sub)process' SYS$OUTPUT buffer.
/[NO]SWAPControls whether the server process may be swapped out of the balance set (default is swapping disabled).
/[NO]SYSUAF[=ID,
PROXY,SSL,WASD]
Allows or disallows (D) username authentication using the server system's SYSUAF (16.10 - SYSUAF-Authenticated Users), the optional "SSL" keyword causes SYSUAF authentication to be available only via "https:" requests (18 - Secure Sockets Layer), the optional "PROXY" keyword allows SYSUAF proxying, and the optional "ID" keyword makes SYSUAF authentication only available to account possessing a specific identifier (16.10 - SYSUAF-Authenticated Users). The "WASD" keyword makes the deprecated, "hard-wired" WASD identifier environment available to this server. See 16.10.3 - WASD "Hard-Wired" Identifiers.
/USERFor VMS 6.2 and later this qualifier allows the /DETACH qualifier to directly create a detached process executing as the specified username.
/VALBLK[=16|64]For server to (try) to use either pre-VMS V8.2 16 byte lock value block or the VMS V8.2 and later 64 byte lock value block.
/VERSIONDisplays the executable's version string and the copyright notice.
/[NO]WATCH=Controls the use of the WATCH reporting facility. See 20 - WATCH Facility for further details.


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