[next] [previous] [contents] [full-page]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
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:
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.
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
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
This procedure serves two purposes.
See HT_ROOT:[EXAMPLE]STARTUP_SERVER.COM
Other resources required or consumed by the package.
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.
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.
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.
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.
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).
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