[next] [previous] [contents] [full-page]4.1 - Package UNZIP
4.2 - ODS-5 Volumes
4.3 - Accessible Volume
4.4 - Package Directory Structure
4.5 - TCP/IP Infrastructure
4.6 - SYSUAF and RIGHTSLIST WARNING!
4.7 - Installation DCL Procedure
4.8 - Update DCL Procedure
4.9 - Quick-Check
4.10 - "Clone" Procedure
4.11 - Re-Linking
4.12 - VMS 6.0 and 6.1
4.13 - VMS 5.5-n
4.14 - Local Setup Suggestions
4.15 - Reporting Problems
The WASD package is distributed as ZIP archives.
It generally pays to use the latest version of VMS UNZIP available.
Archives will contain a comment about the minimum version required, check that
as described in the next paragraph. To show the version of the current UNZIP
utility, use
$ UNZIP -v
The ZIP archive will contain brief installation instructions. Use the
following command to read this and any other information provided.
$ UNZIP -z device:[dir]archive.ZIP
It is recommended to check the integrity of, then list the contents of, the
archive before UNZIPing.
$ UNZIP -t device:[dir]archive.ZIP
$ UNZIP -l device:[dir]archive.ZIP
The archive will have the structure:
Archive: DKA0:[WASD]HTROOT921.ZIP;1
WASD VMS Hypertext Services, Copyright (C) 1996-2007 Mark G.Daniel.
This package (all associated programs), comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.
* Full release of v9.2.1 (May 2007)
**************************************************
*** CONTAINS SOURCE FILES, DOCUMENTATION, ETC. ***
**************************************************
Package must be built using INSTALL or UPDATE as described below.
* To install files:
$ SET DEFAULT device:[000000]
$ UNZIP device:[dir]HTROOT921.ZIP
* To build/link images use the appropriate one of:
$ @device:[HT_ROOT]INSTALL
$ @HT_ROOT:[000000]UPDATE
* NOTE: Accounting data will be zeroed when v9.2 first starts.
**************************************
*** UPGRADING from v8.4 or EARLIER ***
**************************************
WASD v8.5 thru v9.2 uses a different lock naming schema.
Be sure to shut down any running server before beginning the update.
VMS file attributes saved ... use UnZip 5.2+ on OpenVMS
Archive created 19-MAY-2007
Length Date Time Name
-------- ---- ---- ----
0 05-19-07 07:47 ht_root/000000/
0 05-19-07 07:47 ht_root/axp-bin/
0 05-19-07 07:47 ht_root/axp/
0 05-19-07 07:47 ht_root/cgi-bin/
0 05-19-07 07:47 ht_root/doc/
0 05-19-07 07:48 ht_root/example/
0 05-19-07 07:48 ht_root/exercise/
2734 03-06-03 17:20 ht_root/favicon.ico
...
1433 04-25-02 13:58 ht_root/src/utils/wb_exercise.com
89932 10-26-06 14:31 ht_root/src/utils/wotsup.c
1990 05-10-05 09:21 ht_root/src/utils/wotsup.com
263 10-14-02 16:55 ht_root/startup/readme.html
342 11-19-02 05:31 ht_root/vax-bin/readme.html
499 12-26-03 21:09 ht_root/vax/readme.html
-------- -------
14978508 819 files
4.1 - Package UNZIP
The archive contains the complete directory tree. Hence it is necessary
to SET DEFAULT into the top-level directory of the volume the package is to be
installed on.
$ SET DEFAULT device:[000000]
It should be unarchived to restore the VMS file system characteristics.
$ UNZIP device:[dir]archive.ZIP
Source Archive, Object Module Archives
The complete package, source code, documentation, examples, etc., is provided in a single main archive. Installation and other build procedures allow the entire package to be compiled and linked from this if prefered. This requires a later version of DEC C (preferably v5.n or greater). VAX C is no longer supported.
In addition, for those unable or not wishing to fully build the distribution, three other platform-specific archives are available, AXP (Alpha) IA64 (Itanium) and VAX, containing a complete set of object modules, allowing the package to be built via a link operation only.
If a complete build is planned then only the main archive is required. If
a link-only build then an additional archive for each architecture must be
UNZIPped as described above. This applies to both full installations and
subsequent updates. The archives will be clearly identified with the
architecture type, as illustrated in this example.
$ UNZIP device:[dir]archive-AXP.ZIP
$ UNZIP device:[dir]archive-IA64.ZIP
$ UNZIP device:[dir]archive-VAX.ZIP
NOTE
The WASD distribution and package organisation fully supports mixed-architecture clusters (AXP, Itanium and/or VAX in the one cluster) as one integrated installation.
When installing an archive as an update to an existing installation consider the following.
$ BACKUP HT_ROOT:[000000...] location:HTROOT.BCK/SAVE/VERIFY $ ZIP "-V" location:HTROOT.ZIP device:[HT_ROOT...]*.* $ ZIP "-T" location:HTROOT.ZIPIf using ZIP then ensure that a previous version of the target ZIP file does not already exist. If it does then that version is updated, a new version is not created.
$ SET DEFAULT device:[000000] $ UNZIP device:[dir]archive-AXP.ZIP ht_root/src/httpd/obj_axp/*.*
The WASD package can be installed on and used from ODS-5
(extended file specification) volumes. Note that the installation procedures
and file system organisation of the package tree has been designed for ODS-2
compliance. (Of course the issue of installing WASD on an ODS-5 volume is
completely separate from the ability to serve the contents of an ODS-5 volume!)
4.3 - Accessible Volume
Unlikely as it might be to install the package on a private or otherwise
protected volume, the server and scripting accounts being unprivileged in
themselves, require access sufficient to read, write and delete files from the
volume (disk). The following illustrates how to check this and what the
protections should look like. Generally any device that an unprivileged user
can use the server accounts can use.
$ SHOW SECURITY /CLASS=VOLUME $1$DKA0:
ALPHASYS object of class VOLUME
Owner: [1,1]
Protection: (System: RWCD, Owner: RWCD, Group: RWCD, World: RWCD)
Access Control List: <empty>
4.4 - Package Directory Structure
The package directories and content are organised as follows. Note that only some of these can be accessed by the server account (and therefore seen in server-generated directory listings) due to directory and file protections (7.1 - Recommended Package Security).
|
The WASD installation procedure does, and to a lesser degree the update procedure can, make additions and/or modifications to SYSUAF.DAT and RIGHTLIST.DAT, for default server and scripting accounts and to facilitate their access to the package directory tree.
Also, when the server image begins execution it may add an identifier, required for script process management, to RIGHTSLIST.DAT.
These behaviours must be considered in site environments where such changes
are prohibited or closely controlled.
4.7 - Installation DCL Procedure
The INSTALL.COM procedure assists with the first installation of WASD. It provides a vanilla setup, using the standard directories and account environment described in this document. All sections prompt before performing any action and generally default to "no". Read the information and questions carefully!
After UNZIPing the package do the following:
$ SET DEFAULT device:[HT_ROOT]
$ @INSTALL
It performs the following tasks:
Support files to consider when customizing startup, etc. (see 5.3 - Account Support Files for further detail):
The UPDATE.COM procedure assists with subsequent updates of WASD. It assumes a vanilla setup, using the standard directories and account environment described in this document. All sections prompt before performing any action and generally default to "no". Read the questions carefully!
Of course it is best (read mandatory) for the server to be shut down during
an update!
$ HTTPD/DO=EXIT/ALL
After UNZIPing the updated package do the following:
$ SET DEFAULT HT_ROOT:[000000]
$ @UPDATE
It provides the following functions:
If declined during the update procedure the post-update steps 6 and 7 can
be performed at any subsequent time using
$ SET DEFAULT HT_ROOT:[000000]
$ @UPDATE CLEANUP
$ PURGE [...]
4.9 - Quick-Check
Once installed or updated it is possible to check the basic package at any
time using the [INSTALL]DEMO.COM procedure. This invokes the server image
using the /DEMO qualifier allowing some behaviours not possible under general
use. Follow the displayed instructions. Basically, the server should start
and become reachable via port number 7080. So, to test availability, using
your prefered browser enter the URL listed on line starting with
"%HTTPD-I-SERVICE" and the WASD welcome page should be displayed.
$ @HT_ROOT:[INSTALL]DEMO.COM
*******************************
* WASD PACKAGE DEMONSTRATOR *
*******************************
If you have the SSL package then just add "SSL" as parameter 1!
When finished using demonstrator abort server execution using control-Y
(a subprocess will be spawned to preserve current process environment)
Use a browser to access the "%HTTPD-I-SERVICE" shown when the server starts.
The server will be running in promiscuous mode!
Any username with the password specified below can be used for authentication.
Enter a string to use as a password when later prompted by your browser.
Password (for demo authentication)? []: anyoldpassword
%DCL-S-SPAWNED, process SYSTEM_50032 spawned
%DCL-S-ATTACHED, terminal now attached to process SYSTEM_50032
%HTTPD-I-SOFTWAREID, HTTPd-WASD/9.2.1 OpenVMS/AXP
WASD VMS Hypertext Services, Copyright (C) 1996-2007 Mark G.Daniel.
This package (all associated programs), comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.
%HTTPD-I-STARTUP, 28-OCT-2007 01:04:28
%HTTPD-I-SYSTEM, Digital Personal WorkStation VMS V8.3
%HTTPD-W-SYSPRV, operating with implicit SYSPRV (UIC group 1)
%HTTPD-I-TCPIP, HP TCPIP$IPC_SHR V5.6-9 (22-JUN-2006 20:21:19.28)
%HTTPD-I-MODE, INTERACTIVE
%HTTPD-I-ODS5, supported by Alpha VMS V8.3
%HTTPD-I-GMT, +09:30
%HTTPD-I-INSTANCE, supervisor
%HTTPD-I-GBLSEC, created global section of 16 page(let)s
%HTTPD-I-INSTANCE, 1 process
%HTTPD-I-INSTANCE, process name HTTPd:7080
%HTTPD-W-AUTH, 1 informational, 1 warning, 0 errors at load
1.w PROMISCUOUS authenticating any username with specified password!
2.i Cache for 32 records of 768 bytes in local storage of 49 page(let)s
%HTTPD-W-MAP, 1 informational, 0 warning, 0 errors at load
1.i ODS-5 processing enabled
%HTTPD-I-SCRIPTING, as HTTP$NOBODY
%HTTPD-I-DCL, subprocess scripting
%HTTPD-I-ACTIVITY, created global section of 992 page(let)s
%HTTPD-I-SERVICE, http://klaatu.private.net:7080
%HTTPD-I-DEMO, demonstration mode
1.i subprocess scripting
2.i promiscuous authentication
3.i directory access control files ignored
4.i [DirAccess] enabled
5.i [DirMetaInfo] enabled
6.i [DirWildcard] enabled
7.i [Logging] disabled
8.i [ReportBasicOnly] disabled
9.i [ReportMetaInfo] enabled
%HTTPD-I-BEGIN, 28-OCT-2007 01:04:28, accepting requests
When http://the.host.name:7080 is accessed the browser should display the package home page
NOTE
The WASD server which is started by the [INSTALL]DEMO.COM procedure does not have the full environment setup at that time. It is deliberately limited to the single process context. For instance, do not try to execute the command-line directives described in this document.
The [INSTALL]CLONE.COM procedure assists in creating a ZIP archive
of an existing WASD installation suitable for recreating the server on another
system without the necessity of a full installation. This could be used to
populate a series of systems with pre-configured servers.
4.11 - Re-Linking
After a major update to the operating system the package may refuse to
start, reporting a message like:
%DCL-W-ACTIMAGE, error activating image WHAT$EVER
-CLI-E-IMGNAME, image file DKA0:[SYS0.SYSCOMMON.][SYSLIB]WHAT$EVER_SHR.EXE
-SYSTEM-F-SHRIDMISMAT, ident mismatch with shareable image
This implies the executables require re-linking for your particular version
of VMS. This can be accomplished quite simply, perform the linking section
only of the update DCL procedure, 4.8 - Update DCL Procedure.
4.12 - VMS 6.0 and 6.1
Persona scripting requires a minimum VMS V6.2 to provide the $PERSONA services required for this functionality. If unsure about persona scripting please consult the "Scripting Overview" document. Equivalent functionality on earlier versions of VAX VMS is available using the PERSONA_MACRO build option. This will be prompted for by the INSTALL.COM and UPDATE.COM procedures if VAX VMS V6.0 or V6.1 is detected. It is completely optional functionality, the default for these versions is merely to report that persona scripting is unavailable.
A kernel-mode MACRO module is used to provide sufficient functionality to support non-server account scripting. This module makes a momentary modification to the server process username in kernel data structures allowing a detached (scripting) process to be created under that account. The standard WASD server STARTUP.COM procedure will detect whether the MACRO module has been compiled into the executable and INSTALL the image with CMKRNL privilege if required.
NOTE
Although this approach has been used by a number of tools and applications and has proved quite reliable it is still a mechanism unsupported by the operating system proper and so may have a (potentially) undesirable impact on system integrity.
An alternative is to run the server as a NETWORK mode process.
4.13 - VMS 5.5-n
WASD is only officially supported for VMS V6.0 or greater. However pre-7.n versions have been known to successfully build and run under VMS V5.5-n. It will, in all probability, require the AACRTL060 kit (which is part of DECC for this version of VMS, or can be obtained and installed separately).
One issue was a difficulty in using the CGI-BIN logical. This was isolated
to the hyphen it contains and resolved by changing the definition of this in
STARTUP.COM, using instead "CGI-BIN". This is now the default for the
example startup procedure, allowing both 5.5-n and later VMS
versions to function correctly.
4.14 - Local Setup Suggestions
Package updates will never contain anything in these directories:
To prevent the overwriting of local configuration files it is suggested
these be placed in the HT_ROOT:[LOCAL] directory. Local authentication
databases could also be placed in the [LOCAL] directory. Startup files can be
placed where-ever the local site manages system startup. These could be placed
in the HT_ROOT:[STARTUP] directory.
4.15 - Reporting Problems
This package, as is generally the case with freeware, is mainly developed and supported outside of the author's main occupation and working hours. Reports of problems and bugs (while not necessarily welcome :-), as well as general queries, are responded to as soon as practicable. If the documentation is inaccurate or could benefit from clarification in some area please advise of this also (the better the documentation the less queries you have to field personally ... or so the theory goes).
With all reports please include the version of the server or script, and the hardware platform, operating system and TCP/IP package and version in use.
If a server error message is being generated please examine the HTML source of the error page. The "<META...>" information contains version information as well as valuable source code module and line information. Include this with the report.
If the server is exiting with a server-generated error message this information also contains module and line information. Please include this with the report.
The WATCH facility (20 - WATCH Facility) is often a powerful tool for problem investigation. It is also very useful when supplying details during problem resolution. When supplying WATCH output as part of a problem report please ZIP the file and include it an an e-mail attachment. Mailers often mangle the report format making it difficult to interpret.
Image crash dumps may also be generated, although these are of less value than the case of the previous two.
Reports may be e-mailed to
Mark.Daniel@wasd.vsm.com.au
Should the above address present problems or provide no response for an
extended period then use
Mark.Daniel@dsto.defence.gov.au