NOTE: SOME FUNCTIONALITY EMPLOYS JAVASCRIPT WASD Install and Update – Server Account and Environment

WASD Install and Update

4.Server Account and Environment

4.1VMS Server Account
4.2VMS Scripting Account
4.3Account Support Files
4.4Global Pages/Sections
4.5Logical Names
4.5.1WASD Name Table
4.6Server Startup

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. BYTLM in particular, and then BIOLM, DIOL, FILLM and PGFLQUO, are all 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 (see WATCH Facility of WASD Features and Facilities) provides some feedback on server BYTLM usage.

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.

Later versions of TCP/IP Services for OpenVMS seem to have large default values for socket send and receive buffers. MultiNet and TCPware are reported to improve transfer of large responses by increasing low default values for send buffer size. The WASD global configuration directives [SocketSizeRcvBuf] and [SocketSizeSndBuf] allow default values to be adjusted. WATCH can be used to report network connection buffer values.


4.1VMS 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: WASD_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

4.2VMS 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: WASD_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

4.3Account 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 WASD_ROOT:[EXAMPLE]
HTTPd Executables

Two server executables can be built by the package.

Privileged Image

As the HTTP$SERVER account should be completely unprivileged, and the HTTPd image requires ALTPRI, CMKRNL, DETACH, NETMBX, TMPMBX, OPER, PRMGBL, PRMMBX, PSWAPM, SECURITY, SYSGBL, SYSLCK, SYSNAM, SYSPRV and WORLD privileges (see the WASD_ROOT:[SRC.HTTPD]READMORE.TXT) document for a description of how and why the server uses these privileges).

It is installed using a command similar to the following:

$ INSTALL = "$SYS$SYSTEM:INSTALL/COMMAND_MODE" $ INSTALL ADD WASD_EXE:HTTPD.EXE - /PRIVILEGE=(ALTPRI,CMKRNL,DETACH,OPER,PRMGBL,PRMMBX,PSWAPM,- SECURITY,SYSGBL,SYSLCK,SYSNAM,SYSPRV,WORLD)
DCL Procedure STARTUP.COM
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 this way requires no modifications 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.

$ @DKA0:[WASD_ROOT.STARTUP]STARTUP WASD_DECNET=1 WASD_SSL=1 - WASD_SSL_CERTIFICATE="WASD_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 = "WASD_ROOT:[LOCAL]ALPHA.PEM" $ @DKA0:[WASD_ROOT.STARTUP]STARTUP
$ @DKA0:[WASD_ROOT.STARTUP]STARTUP WASD_DECNET=1 WASD_BATCH_QUEUE=THIS$BATCH

Check the procedure itself for detail on symbol names and functionality. See WASD_ROOT:[EXAMPLE]STARTUP.COM

DCL Procedure STARTUP_LOCAL.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. For example, a STARTUP.COM defined logical name could be modified here before the server proper is actually started. See WASD_ROOT:[EXAMPLE]STARTUP_LOCAL.COM

DCL Procedure STARTUP_SERVER.COM
STARTUP_SERVER.COM

This procedure serves two purposes.

  1. 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 server restarts and exits.
WASD_ROOT:[EXAMPLE]STARTUP_SERVER.COM

It is recommended to pass server startup command-line parameters using the WASD_SERVER_STARTUP logical name that this procedure checks for and uses if present. If this is defined the contents are applied to the server image when executed. It can be explicitly defined before WASD startup.

$ DEFINE /SYSTEM /EXECUTIVE WASD_STARTUP_SERVER "/SYSUAF=ID" $ @DKA0:[WASD_ROOT.STARTUP]STARTUP

The 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 = "WASD_ROOT:[LOCAL]ALPHA.PEM" $ WASD_STARTUP = "/SYSUAF=ID" $ @DKA0:[WASD_ROOT.STARTUP]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 WASD_STARTUP_SERVER "/SYSUAF=(SSL,ID)" $ HTTPD /DO=RESTART=NOW

4.4Global Pages/Sections

Various accounting, cache and other shared data used by the server is provided by shared global memory. These requires one permananet global section (SYSGEN parameter GBLSECTIONS) and a number of permanent global pages (SYSGEN parameter GBLPAGES) per item. The number of items varies depending on configuration.

Global Sections
Item Description Usage
Accounting Accumulates various data provided to the Server Administration Statistics report and the HTTPMON utility required
Activity Provides data to the Server Administration Activity Report graph required
Authentication When multiple WASD Instances are configured provides a shared authentication cache optional
Proxy Verification When multiple WASD Instances are configured provides an shared proxy verification cache optional
SSL Session Cache When SSL is used and multiple WASD Instances are configured provides a shared SSL session cache optional

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. Server process log startup messages advise on current usage.

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

4.5Logical Names

WASD uses an independent logical name table (see 4.5.1 WASD Name Table below). Versions prior to 10 used the SYSTEM table and a substantially different naming schema.

The following logical names are used in the operation of the package. These are usually created by STARTUP.COM during server startup.

Package Logical Names
Logical Name Table Description
CGI-BIN WASD (Hyphen) 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.
CGI_BIN WASD (Underscore) Directory containing architecture-neutral script files.
CGI_EXE WASD Directory containing architecture-specific script executables.
HT_EXE WASD Pre-v10.0 backward compatibility for WASD_EXE.
HT_LOGS WASD Pre-v10.0 backward compatibility for WASD_LOG.
HT_ROOT SYSTEM Pre-v10.0 backward compatibility for WASD_ROOT.
HT_SCRATCH WASD Pre-v10.0 backward compatibility for WASD_SCRATCH.
WASD_AXP WASD Directory containing Alpha executable images (WASD_ROOT:[AXP]).
WASD_AUTH WASD Directory containing authentication/authorization databases (files, (WASD_ROOT:[LOCAL])).
WASD_CGI_AXP WASD Directory containing Alpha script executables (WASD_ROOT:[AXP-BIN]).
WASD_CGI_IA64 WASD Directory containing Itanium script executables (WASD_ROOT:[IA64-BIN]).
WASD_CGI_X86_64 WASD Directory containing x86-64 script executables (WASD_ROOT:[X86_64-BIN]).
WASD_CONFIG WASD Location of the configuration files. Can be defined as a search list.
WASD_CONFIG_AUTH WASD Location of the authentication/authorization configuration file.
WASD_CONFIG_GLOBAL WASD Location of the configuration file.
WASD_CONFIG_MAP WASD Location of the mapping rule file.
WASD_CONFIG_MSG WASD Location of the message file.
WASD_CONFIG_SERVICE WASD Location of the optional service (virtual host) configuration file.
WASD_DECNET_CGI_OBJECT SYSTEM Locates the supporting DCL procedure. DECnet objects are system-global.
WASD_DECNET_OSU_OBJECT SYSTEM Locates the supporting DCL procedure. DECnet objects are system-global.
WASD_EXE WASD Directory containing the executable images.
WASD_FILE_DEV[n] SYSTEM Locates the DCL procedure that will integrate the specified environment's logical name table into the processes' LNM$FILE_DEV (see above).
WASD_GMT WASD 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.
WASD_IA64 WASD Directory containing Itanium executable images.
WASD_LOG WASD 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.
WASD_LOGS WASD Optional definition, for convenient log file specification.
WASD_ROOT SYSTEM Location of WASD Web Services directory tree, as a concealed device.
WASD_SCRATCH WASD Location of an optional directory that scripts can use for temporary storage. Must be read+write+delete accessible to the server account. The WASD_CONFIG_GLOBAL [DclCleanupScratchMinutesMax] directive controls whether automatic cleanup scans of this area delete any files that are older than [DclCleanupScratchMinutesOld].
WASD_SITELOG WASD Location of the optional plain-text site log file.
WASD_SSL_CAFILE WASD When using the SSL executable this logical locates the optional Certificate Authority list file.
WASD_SSL_CERT WASD When using the SSL executable this logical locates the default certificate.
WASD_SERVER_LOGS WASD Location of the server process logs.
WASD_STARTUP_SERVER WASD Used to pass parameters to the server image startup command line.
WASD_X86_64 WASD Directory containing x86-64 executable images.
Pre-v10 Logical Names

The pre-v10.0.0 logical names (e.g. HTTPD$MAP) are deprecated and will be obsoleted in a future version. The server process log issues warnings such as HTTPD-W-DEPRECATED, change HTTPD$MAP to WASD_CONFIG_MAP (soon!) for any it finds during startup.

4.5.1WASD Name Table

In an effort to localise WASD-related logical names and avoid polluting the SYSTEM logical name table WASD version 10 creates it's own world-readable, system-writable name table, and adds it to LNM$SYSTEM_DIRECTORY.

$ SHOW LOGICAL WASD_TABLE/TABLE=LNM$SYSTEM_DIRECTORY "WASD_TABLE" [table] = "" (LNM$SYSTEM_DIRECTORY)

WASD logical names are then defined in that table leaving the SYSTEM table with just a few essential names.

$ SHOW LOGICAL CGI*,HT*,WASD*,WWW* (LNM$PROCESS_TABLE) (LNM$JOB_81E3D580) (WASD_TABLE) "CGI-BIN" = "DKA0:[WASD_ROOT.CGI-BIN.]" = "DKA0:[WASD_ROOT.AXP-BIN.]" "CGI_BIN" = "WASD_ROOT:[CGI-BIN]" "CGI_EXE" = "WASD_ROOT:[AXP-BIN]" "HTBIN" = "CGI-BIN:[000000]" "HT_CACHE_ROOT" = "DKA0:[HT_CACHE.]" "HT_EXE" = "WASD_ROOT:[AXP]" "HT_LOGS" = "WASD_ROOT:[LOG]" "HT_SCRATCH" = "WASD_ROOT:[SCRATCH]" "WASD_AUTH" = "WASD_ROOT:[LOCAL]" "WASD_AXP" = "WASD_ROOT:[AXP]" "WASD_CACHE_ROOT" = "DKA0:[HT_CACHE.]" "WASD_CGILIBSHR32" = "CGI_EXE:CGILIBSHR32.EXE" "WASD_CGI_AXP" = "WASD_ROOT:[AXP-BIN]" "WASD_CGI_BIN" = "WASD_ROOT:[CGI-BIN]" "WASD_CGI_EXE" = "WASD_ROOT:[AXP-BIN]" "WASD_CGI_IA64" = "WASD_ROOT:[IA64-BIN]" "WASD_CGI_X86_64" = "WASD_ROOT:[X86_64-BIN]" "WASD_CONFIG" = "WASD_ROOT:[LOCAL]" "WASD_CONFIG_AUTH" = "WASD_CONFIG:HTTPD$AUTH.CONF" "WASD_CONFIG_GLOBAL" = "WASD_CONFIG:HTTPD$CONFIG.CONF" "WASD_CONFIG_MAP" = "WASD_CONFIG:HTTPD$MAP.CONF" "WASD_CONFIG_MSG" = "WASD_CONFIG:HTTPD$MSG.CONF" "WASD_CONFIG_SERVICE" = "WASD_CONFIG:HTTPD$SERVICE.CONF" "WASD_EXE" = "WASD_ROOT:[AXP]" "WASD_HTTPD_EXE" = "WASD_EXE:HTTPD_SSL.EXE" "WASD_IA64" = "WASD_ROOT:[IA64]" "WASD_JAVA" = "WASD_ROOT:[JAVA]" "WASD_LOCAL" = "WASD_ROOT:[LOCAL]" "WASD_LOGS" = "WASD_ROOT:[LOG]" "WASD_SCRATCH" = "WASD_ROOT:[SCRATCH]" "WASD_SCRIPT" = "WASD_ROOT:[SCRIPT]" "WASD_SCRIPT_LOCAL" = "WASD_ROOT:[SCRIPT_LOCAL]" "WASD_SERVER_LOGS" = "WASD_ROOT:[LOG_SERVER]" "WASD_SSL_CAFILE" = "WASD_CONFIG:CA-BUNDLE_CRT.TXT" "WASD_SSL_CERT" = "WASD_CONFIG:HTTPD.PEM" "WASD_STARTUP" = "WASD_ROOT:[STARTUP]" "WASD_STARTUP_SERVER" = "/SYSUAF=(ID,SSL)/PERSONA=RELAXED/PROFILE" "WASD_X86_64" = "WASD_ROOT:[X86_64]" "WWW_ROOT" = "DKA0:[WASD_ROOT.SRC.OSU]" "WWW_SCRIPT_MAX_REUSE" = "999" (LNM$GROUP_000001) (LNM$SYSTEM_TABLE) "HT_ROOT" = "DKA0:[WASD_ROOT.]" "WASD_DECNET_CGI_OBJECT" = "DKA0:[WASD_ROOT.CGI-BIN]CGIWASD.COM" "WASD_DECNET_OSU_OBJECT" = "DKA0:[WASD_ROOT.CGI-BIN]WWWEXEC.COM" "WASD_FILE_DEV" = "DKA0:[WASD_ROOT]WASD_FILE_DEV.COM" "WASD_ROOT" = "DKA0:[WASD_ROOT.]" (LNM$SYSCLUSTER_TABLE) (DECW$LOGICAL_NAMES)

As can be seen the number of LNM$SYSTEM_TABLE names is small, five in this example (though it can vary). Logical name WASD_FILE_DEV locates a procedure to insert the WASD_TABLE into a process' LNM$FILE_DEV to make the table names available. Until that is done they are not visible without an explicit /TABLE=WASD_TABLE. The server automatically uses the procedure for itself and scripting processes. Site admins can simply

$ @WASD_FILE_DEV
at the command-line or in their LOGIN.COM to have it done for their interactive session(s). This procedure location is variable within the file-system and needs to be located and accessed without initially knowing that location.

The WASD_ROOT logical provides a convenient, global logical location for the primary (default) WASD environment. HT_ROOT is used to provide pre-v10 backward-compatibility with existing sites. (If yours does not need the name you can deassign it during server startup.)

The WASD_DECNET_CGI_OBJECT and WASD_DECNET_OSU_OBJECT names provide global locations for the two DECnet scripting environments. These logicals are defined when a site uses the [STARTUP]STARTUP_DECNET.COM procedure. It is necessary to provide a global location for these with multiple WASD environments because DECnet objects are global entities. The one object must provide an infrastructure for potentially multiple WASD environments.

Other SYSTEM logical names, WASD_TABLE+n name tables, and WASD_FILE_DEVn logical names are used for non-primary WASD environments (see Instances and Environments of WASD Features and Facilities).

4.6Server 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’ in 4.3 Account Support Files. For clarity some esoteric and legacy qualifiers and parameters are not listed in this table.

Server Image Command-Line Parameters
Parameter/Qualifier Description
/ALL[=integer] Has two roles. When starting a server up assigns that server to a specific, non-default WASD environment (see /ENVIRONMENT) When using the server control /DO= using /ALL specifies to do the action to all servers in that particular environment.
/AUTHORIZATION=.. Control authentication and authorisation behaviour.
See Authentication Policy of WASD Features and Facilities.
/CGI_PREFIX= The prefix to the CGI symbol names created for a script (defaults to "WWW_").
See WASD Web Services - Scripting
/CLUSTER Apply control /DO= to all instances in a cluster (default is to current node instance(s) only).
/DETACH= 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.
/ENVIRONMENT= Integer indicating in which environment this server is executing
/GBLSEC=DELETE Allows a monitor-associated permanent global section to be explicitly deleted. When a server starts it creates system-accessible, 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.
/GBLSEC=NOPERM Disables the creation of permanent global sections. They are automatically deleted when the server image exits.
/[NO]LOG[=name] Either disables logging (overrides configuration directive), or enables logging and optionally specifies the log file name (also see section 4.5 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.
/NETWORK Run the server and any scripting processes as NETWORK mode rather than the default detached OTHER mode.
/NOTE=string Annotate the server process log with the specified string. Intended to assist auditing server events such as restarts, maaping reloads and the like.
/OUTPUT=filename Server image <stdout> is redirected to the specified file name. Useful when employing the /SYSPLUS report generator.
/PERSONA[=..] Enables and controls detached process scripting.
See Introduction of WASD Scripting Environment.
/PRIORITY= Server process priority (default is 4).
/[NO]PROFILE Allows SYSUAF-authenticated username security profiles to be used for file access.
/PROMISCUOUS[=password] Server will accept any authentication username/password pair (used for testing, demonstrations, etc.)
/PROXY=string Allows proxy maintainance activities to be executed from the command line (e.g. from batch jobs, etc.).
/SCRIPT=AS=username 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/10.4.0 OpenVMS/AXP SSL").
/[NO]SSL[=..] Controls Secure Sockets Layer protocol behaviour.
See Transport Layer Security of WASD Features and Facilities.
/SYSPLUS Displays CLI equivalent System Report PLUS data. Available for circumstances where the server is unresponsive but an interactive session is available. Requires a 132 character width terminal session.
See System Report PLUS of WASD Features and Facilities.
/[NO]SYSUAF[=..] Controls VMS (SYSUAF) authentication/authorisation behaviour.
See SYSUAF-Authenticated Users of WASD Features and Facilities.
/USER=username For 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.
/VERSION Displays the executable's version string and the copyright notice.
/[NO]WATCH[=..] Controls the use of the WATCH reporting facility.
See WATCH Facility of WASD Features and Facilities.