[next] [previous] [contents] [full-page]19.1 - Access Before Configuration
19.2 - Access Configuration
19.3 - Server Instances
19.4 - HTTPd Server Reports
19.5 - HTTPd Server Revise
19.6 - HTTPd Server Action
19.7 - HTTPd Command Line
19.7.1 - Accounting
19.7.2 - Authentication
19.7.3 - Cache
19.7.4 - DCL/Scripting Processes
19.7.5 - DECnet Scripting Connections
19.7.6 - Instances
19.7.7 - Logging
19.7.8 - Mapping
19.7.9 - Shutdown and Restart
19.7.10 - Secure Sockets Layer
19.7.11 - Throttle
The online Server Administration facility provides a rich collection of functionality, including server control, reports and configuration. Some of these are intended as general administration tools while other provide more detailed information intended for server debugging and development purposes.
The value of the WATCH facility 20 - WATCH Facility as a general configuration and problem-solving tool cannot be overstated.
All server configuration files, with the execption of the authentication databases, are plain text and may be modified with any prefered editor. However the majority of these can also be administered online through a browser. In addition the update facility allows some administration of file system portions of the Web. See 22 - HTTPd Web Update.
Access to many portions of the package is constrained by file protections
and directory listing access files. See
16.10.8 - SYSUAF Profile For Full Site Access for a method for circumventing these
restrictions.
19.1 - Access Before Configuration
It is often a significant advantage for the inexperienced administrator on
a new and largely unconfigured installation to be able to gain access to the
facilities offered by Server Administration, particularly the WATCH facility
(20 - WATCH Facility). This can be done quite simply by using the
authentication skeleton-key (16.11 - Skeleton-Key Authentication). This allows
the site administrator to register a username and password from the
command-line that can be used to gain access to the server. In addition, the
server ensures that requesting an otherwise non-authorized Server
Administration facility generates a challenge which invokes a username/password
dialog at the browser allowing the user to enter the previously registered
username and password and gain access.
Method
$ HTTPD == "$HT_EXE:HTTPD.EXE" $! HTTPD == "$HT_EXE:HTTPD_SSL.EXE" $ HTTPD /DO=AUTH=SKELKEY=_username:password
Note that the username must begin with an underscore, be at least 6 characters, is delimited by a colon, and that the password must be at least 8 characters. By default this username and password remains valid for 60 minutes. Choose strings that are less-than-obvious!
http://the.host.name:port/httpd/-/admin/
$ HTTPD /DO=AUTH=SKELKEY=0
One established the site should make the Server Administration facility a configured facility of the site. The value of it's facilities cannot be overstated. The section 15.1 - SYSUAF/Identifier Authentication provides a short guide to setting up authorization for server administration purposes.
It is also recommended that for production sites the path to these reports
be controlled via authentication and authorization, using both host and
username restrictions, similar to the following:
[WHATEVER-REALM]
/httpd/-/admin/* host.ip.addr,~WebMaster,~WhoEverElse,r+w
If a full authorization environment is not required but
administration via browser is still desired restrict access to browsers
executing on the server system itself, using an appropriate
SYSUAF-authenticated username. Provision of a VMS account for server
administration only is quite feasable, see
16.10.5 - Nil-Access VMS Accounts.
[VMS]
/httpd/-/admin/* #localhost,~username,r+w
If SSL is in use (18 - Secure Sockets Layer) then username/password
privacy is inherently secured via the encrypted communications. To restrict
server administration functions to this secure environment add the following
to the HTTPD$MAP configuration file:
/httpd/-/admin/* "403 Access denied." ![sc:https]
When using the revise capability of the Server Administration
facility is necessary to comply with all the requirements for Web update of
files. This is discussed in general terms in 22 - HTTPd Web Update.
Revision of server configuration files requires path permissions allowing write
access for the username(s) doing the administration, as well as the required
ACL on the target directory (in the following example HT_ROOT:[LOCAL]).
[VMS]
/httpd/-/admin/* #localhost,~username,r+w
/ht_root/local/* #localhost,~username,r+w
It is possible to allow general access to the Server Administration
facility and reports while restricting the ability to initiate server actions
such as a restart! Using the WORLD realm against the path is necessary, for the
obvious security reason, the server administration module will not allow itself
to be used without an authenticated username, provided as a
pseudo-authenticated
"WORLD".
[VMS]
/httpd/-/admin/control/* #localhost,~username,r+w
[WORLD]
/httpd/-/admin/* r
When GZIP compression is configured for the server
(6.5 - GZIP Encoding) it is not by default applied to Server
Admin reports or other pages. It can be applied, selectively if desired, using
mapping rules. For instance, to apply it to all requests not from the local
intranet a rule similar to the following can be added before the Server Admin
path mapping itself.
if (!remote-addr:192.168.0.0/8) set /httpd/-/admin/* response=GZIP=all
pass /httpd/-/admin/* /httpd/-/admin/*
GZIP content-encoding can never be applied to WATCH reports.
19.3 - Server Instances
With a single instance (6.2 - Server Instances) access to Server Administration reports, etc. is always serviced by the one server process. If multiple instances are configured in common with all requests administration requests will be serviced by any one of the associated processes depending on the momentary state of the round-robin distribution.
There are many circumstances where it is preferable to access only the one server. This can be accomplished for two differing objectives.
The latter approach is particularly useful when performing detailed WATCH activities (20 - WATCH Facility).
When multiple per-node instances are executing the Server Administration
pages and reports all include an indication of which process serviced the
request. When accessing no instance in particular the process name is
presented in parentheses after the page title
HTTPd wasd.dsto.defence.gov.au:80
Server Administration (HTTPd:80)
When a particular instance's administration service port is being used the
process name is separated from the page title by a hyphen
HTTPd wasd.dsto.defence.gov.au:80
Server Administration - HTTPd:80
19.4 - HTTPd Server Reports
The server provides a number of internally generated reports. Some of these are of general interest. Others are more for evaluating WASD behaviour and performance for development purposes. These are listed in the approximate order in which they occur top-to-bottom, left-to-right in the menu layout.
It is possible to use this facility standalone, without configuring authorization (19.1 - Access Before Configuration).
DCL module statistics (same information as displayed in the server statistics report). These are cumulative for the entire life of the system (unless zeroed).
Process information shows how many actual processes exist at the time of the report, as indicated by the PID and bolded, non-zero liftime (in minutes). The soft-limit specifies how many CGIplus scripts are allowed to continue existing before the least used is deleted and the hard-limit show how many processes may actually exist at any one time (the margin allows for process deletion latency). A count of how many times the CGIplus processes have been explicitly purged (button available on this report page). The life-time of zombie processes (in minutes, zero implying use of zombies is disabled) and the number that have been purged due to expiry. CGIplus process life-time (in minutes, zero implying indefinite), the number purged due to life-time expiry and the number of CGIplus processes that the server has actually purged (deleted) to maintain the soft-limit margin specified above.
Each of the allocated process data structures is listed. There may be zero up to hard-limit items listed here depending on demand for DCL activities and the life of the server. Items with a PID shown indicate an actual process existing. This can be a zombie process or a CGIplus process. If no process is indicated then the other information represents the state the last time the item's associated process completed. Information includes the script (URL-style path) or DCL command, total count of times the item has been used and the last time it was. The zombie count indicates the number of time the same process finished a request and entered the zombie state. The CGIplus column indicates it is/was a CGIplus script and shows the total number of times that particular script has been/was used. If the process is currently in use the client information show the client host name.
If any processes are associated with any data structure a purge button is provided that forces all processes to be deleted. This can be useful if a new script image is compiled and it is required all scripts now use this. If a script is currently processing a request the process deletion occurs when that processing is complete. The purge button does not force a process to delete, so a second button forces all processes to delete immediately. This can be used to forceably clear errant scripts, etc., but be warned script processing is indiscrimately stopped!
This list will grow, up to the specified configuration maximum, as conconurrent scripting demand occurs. Maintained connections are indicated by the bolded, non-zero lifetime (in minutes). When this reaches zero the task is disconnected. The current/last task for that connection is indicated, along with the number of times the connection was reused and a total number of uses for that list item.
Purge and force buttons allow current links to be broken after request completion or forcibly disconnected.
Two other diagnostic tools are available from the same link. The first, WATCH-peek Report, providing a snapshot of the contents selected internal fields and data structures of the request. This is primarily intended as a problem investiagtion and development tool, and will be of limited value without an understanding of server internals. The second accesses the "peek" internals plus a one-shot WATCH-processing report.
For servers handling a great quantity of concurrent traffic this can generate a very large report. The Supervisor report can also provide a profile of the servers current load.
The statistics are stored in a permanent global section and so carry-over between server restarts. Where multiple instances are executing the data represents an accumulation of all instances' processing. It is enabled by the configuration parameter [ActivityDays]. The Server Administration facility provides several, represented as a period of hours before the present time. Number of requests and bytes sent to the client are represented by a histogram with respective means for each by a line graph. A bar across the column of the request histogram indicates the peak number of concurrent requests during the period. A greyed area indicates no data available for that time (i.e. before the latest server startup, or in the future).
Server startup and shutdown events are indicated by solid, vertical lines the full height of the graph (see example for a restart event).
Activity data is accumulated on a per-minute basis. This is the maximum granularity of any report. When reports are selected that can display less than this one minute granularity (i.e. with periods greater than four hours) the value shown is the peak of the number of minutes sampled for display. This better represents the load on the server than would a mean of those samples.
The graph is an image map, various regions of which allow the selection of other reports with different periods or durations. This allows previous periods to be examined at various levels of detail using the graph for navigation. Various sections may have no mapping as appropriate to the current report.
For multiple hour reports the upper and lower sections have distinct functions. The middle 50% of the upper section allows the same end time (most commonly the current hour) to be examined over twice the current period, in this case it would be over eight hours. The left 25% allows the previous fours hours to be viewed (if such data exists), and for non-current reports the right 25% allows the next four hours to be viewed. The lower half can be divided into sections representing hours or days depending on the period of the current report. This allows that period to be viewed in greater detail. For single hour reports this section, of course, is not mapped.
Remember that the URL of the mapped section will be displayed in the status bar of the browser. As the URL contains time components it is not a difficult task to decipher the URL displayed to see the exact time and period being selected.
The server provides a comprehensive configuration revision facility.
Chapter 16 - Authentication and Authorization covers authentication detail.
The file name and/or location may be specified using HTTPD$SITELOG (Logical Names).
Many of the server activites listed above require server account write access to the directory in which the configuration files are stored. Where an autononmous scripting account is in use (7.5 - Scripting) this poses minimal threat to server configuration integrity.
# HTTPD$MAP pass /ht_root/local/* auth=all
# HTTPD$AUTH ["Web Admin"=WASD_WEBADMIN=id] /httpd/-/admin/* r+w /ht_root/local/* r+w
$ SECHAN /WRITE HT_ROOT:[000000]LOCAL.DIR $ SECHAN /WRITE HT_ROOT:[LOCAL]
$ HTTPD /DO=MAP $ HTTPD /DO=AUTH=LOAD
If a site is using SYSUAF authentication and security profiles enabled
using the /PROFILE startup qualifier (16.10.7 - SYSUAF Security Profile)
then a more restrictive set up is possible, retaining the default no-access to
the [LOCAL] directory. This relies on the administering account(s) having read
and write access to the [LOCAL] directory. It is then not necessary to grant
that to the server account. It is possible to limit the application of VMS
user profiles. This is an example.
# HTTPD$MAP
set /ht_root/local/* profile auth=all
set * noprofile
To use this approach perform steps 1, 2 and 4 from above, substituting the
following for step 3.
$ SECHAN /PACKAGE HT_ROOT:[000000]LOCAL.DIR
$ SECHAN /PACKAGE HT_ROOT:[LOCAL]
$ SECHAN /CONTROL HT_ROOT:[000000]LOCAL.DIR
19.6 - HTTPd Server Action
The server allows certain run-time actions to be initiated. Many of these functions can also be initiated from the command line, see 19.7 - HTTPd Command Line.
When multiple servers are executing on a single node or within a cluster
a JavaScript-driven checkbox appears in the bottom left of the administration
menu. Checking that box applies any subsequently selected action to
all servers!
Control Section
Caution! If changing CGIplus script mapping it is advised to restart the server rather than reload. Some conflict is possible when using new rules while existing CGIplus scripts are executing.
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.
These directives are communicated from the command-line (and Server
Administration page analogue - Control Section) to the
per-node or per-cluster servers using the Distributed Lock Manager. On pre-VMS
V8.2 the command buffer is limited to 15 bytes. From VMS V8.2 the buffer space
available is 63 bytes. In a cluster all systems must support the larger buffer
before WASD enables it. The smaller buffer space limits some of the directives
that take free-form parameters (e.g. /DO=DCL=PURGE=USER=DANIEL).
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. In a
clustered WASD environment the same functionality is available via checkboxes
from the online Server Administration facility.
19.7.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
19.7.2 - Authentication
See 16 - Authentication and Authorization.
The authorization rule file (HTTP$AUTH) may be reloaded using either of
these variants.
$ HTTPD /DO=AUTH
$ 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 (16.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
(19 - Server Administration).
$ HTTPD /DO=AUTH=SKELKEY=_<username>:<password>[:<period>]
19.7.3 - Cache
Server cache control may also be exercised from the Server Administration
page (19 - Server Administration). The file cache
(13 - Cache Configuration) 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
19.7.4 - DCL/Scripting Processes
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 processes, 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 processes and mark busy ones
for deletion when completed processing.
$ HTTPD /DO=DCL=PURGE
For VMS V8.2 and later, a more selective DELETE and PURGE is possible. A
user name, script name, or script file name can be supplied and only matching
tasks have the specified action peformed.
$ HTTPD /DO=DCL=PURGE=USER=username
$ HTTPD /DO=DCL=PURGE=SCRIPT=script-path
$ HTTPD /DO=DCL=PURGE=FILE=script-file-name
19.7.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
19.7.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 (19.6 - HTTPd Server Action).
There are also directives to assist with WATCH activities
(20.1 - Server Instances).
$ HTTPD /DO=INSTANCE=PASSIVE
$ HTTPD /DO=INSTANCE=ACTIVE
19.7.7 - Logging
Server logging control may also be exercised from the server administration menu (19 - 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 14 - Request Processing Configuration.
The mapping rule file (HTTPD$MAP) may be reloaded using either of these
variants.
$ HTTPD /DO=MAP
$ HTTPD /DO=MAP=LOAD
19.7.9 - Shutdown and Restart
Server shutdown may also be exercised from the Server Administration page (19 - 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
19.7.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 []:
19.7.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
For VMS V8.2 and later, a more selective RELEASE and TERMINATE is possible.
A user name or script name can be supplied and only matching requests have the
specified action peformed.
$ HTTPD /DO=THROTTLE=TERMINATE=USER=username
$ HTTPD /DO=THROTTLE=TERMINATE=SCRIPT=script-path