# WASD Hypertext Services - Technical Overview

## 4 - Installation and Update

> 4.1 - Source Archive, Object Module Archives
> 4.2 - Accessable Volume
> 4.3 - ODS-5 Volumes
> 4.4 - Package Directory Structure
> 4.5 - Installation DCL Procedure
> 4.6 - Update DCL Procedure
> 4.7 - Quick-Check
> 4.8 - "Clone" Procedure
> 4.9 - Re-Linking
> 4.10 - VMS 6.0 and 6.1
> 4.11 - VMS 5.5-n
> 4.12 - Local Setup Suggestions
> 4.13 - Reporting Problems

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

The WASD package and updates will always be 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 UNZIPping.

      $ UNZIP -t device:[dir]archive.ZIP
      $ UNZIP -l device:[dir]archive.ZIP

###
Paranoid?

Are you sure you got what you thought you did? Not keen on importing even one trojan into your site? You may wish to confirm the archive you are about to install is what was originally released. The MD5DIGEST utility may ease your (now) troubled mind. See 23.9 - MD5digest.

###
Installation UNZIP

For complete package distributions the archive will contain the complete directory tree. Hence to install or do a complete update it is necessary to SET DEFAULT into the top-level directory of the disk the package is to be installed on.

      $ SET DEFAULT device:[000000]

A complete installation/update will have the structure:

       Archive:  HT_ROOT:[000000]HTROOT430.ZIP;1

        WASD (HFRD) VMS Hypertext Services, Copyright (c) 1996,1997 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.

         *  Complete v4.3.0 package.
         *  $ SET DEFAULT device:[000000]
         *  $ UNZIP "-V" device:[dir]HTROOT430.ZIP

        VMS file attributes saved ... use UnZip 5.n+ on OpenVMS

        Archive created 1-AUG-1997

        Length    Date    Time    Name
        ------    ----    ----    ----
             0  07-30-97  14:15   ht_root/$_read_1st/
             0  07-30-97  14:15   ht_root/aacrt060/
             0  07-30-97  14:15   ht_root/auth/
             0  07-30-97  14:15   ht_root/axp/
          5360  07-30-97  13:23   ht_root/changes.html
             0  07-30-97  14:15   ht_root/doc/
       .
       .
       .
         16896  07-30-97  09:23   ht_root/vax/wwwrkout.exe
        ------                    -------
      19109754                    996 files

###
Update UNZIP

For updates to portions of the package only the tree below HT_ROOT:[000000] is provided, hence it is necessary to SET DEFAULT to HT_ROOT:[000000] before UNZIPping.

      $ SET DEFAULT HT_ROOT:[000000]

An update will have the structure:

       Archive:  HT_ROOT:[000000]HTROOT430_UPD_01.ZIP;1

        WASD (HFRD) VMS Hypertext Services, Copyright (c) 1996,1997 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.

         *  Mostly minor updates to scripts and utilities for the v4.3.0 package.
         *  A couple nuisance-value-bugs have also been fixed in these.
         *  SDM2HTM can now generate <FRAMESET> documents (see [DOC]*.COM)

        VMS file attributes saved ... use UnZip 5.n+ on OpenVMS

        Archive created 6-AUG-1997

        Length    Date    Time    Name
        ------    ----    ----    ----
         42957  08-04-97  07:57   src/utils/wwwrkout.c
         59664  08-04-97  07:57   src/utils/obj_axp/wwwrkout.obj
         19674  08-04-97  07:57   src/utils/obj_vax/wwwrkout.obj
         26624  08-04-97  07:57   axp/wwwrkout.exe
       .
       .
       .
         45056  08-05-97  11:02   vax/sdm2htm.exe
           617  08-05-97  09:23   doc/all_docs_framed.com
            44  08-05-97  09:23   doc/all_docs_not_framed.com
           544  08-05-97  09:22   doc/readme.html
        ------                    -------
       2773107                    90 files

###
Existing Installations

When installing either a full archive or to a lesser extent an update archive "over the top" of an existing installation consider the following.

- Some insurance on the directory tree is recommended in case the update should fail or otherwise be unusable or problematic (of course, this is good advice whenever about to make major changes to anything!) This may be in the format of a regular site backup, special pre-update backup, or special pre-update ZIP archive of the directory tree. The latter two could be accomplished using commands similar to the following:

        $ BACKUP HT_ROOT:[000000...] location:HTROOT.BCK/SAVE/VERIFY

        $ ZIP "-V" location:HTROOT.ZIP device:[HT_ROOT...]*.*
        $ ZIP "-T" location:HTROOT.ZIP

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

- For existing files a new version is created (the first time this is about to occur the UNZIPper requests permission - either "A" for all, or "y" or "n" or a per-file basis).

- It is possible to selectively extract portions of a tree if something has become damaged. This would be accomplished by specifying what needs to be extracted from the archive (instead of the default all), as illustrated by the following example where only the Alpha object modules are extracted.

        $ SET DEFAULT device:[000000]
        $ UNZIP "-V" device:[dir]archive-AXP.ZIP ht_root/src/httpd/obj_axp/*.*

###
4.1 - 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, two other platform-specific archives are available, AXP (Alpha) 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 "-V" device:[dir]archive-AXP.ZIP
      $ UNZIP "-V" device:[dir]archive-VAX.ZIP

> NOTE

> The WASD distribution and package organisation fully supports mixed-architecture clusters (AXP, IA64 and/or VAX in the one cluster) as one integrated installation.

###
4.2 - Accessable 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.3 - ODS-5 Volumes

The WASD package has been successfully 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. As long as this is maintained there should be no issues with actually having it resident on an extended file system compliant volume. (Of course the issue of installing WASD on an ODS-5 volume is completely separate from it's ability to serve the contents of an ODS-5 volume!)

###
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 (and therefore seen in server-generated directory listings) due to directory and file protections (7.1 - Recommended Package Security).

Package Directory Structure

Directory | Description
| [AXP-BIN] | Alpha executable script files
| [AXP] | Alpha build and utility area | [CGI-BIN] | architecture-neutral script files | [DOC] | package documentation | [EXAMPLE] | package examples | [EXERCISE] | package test files | [HTTP$NOBODY] | scripting account default home area | [HTTP$SERVER] | server account default home area | [IA64-BIN] | IA64 executable script files | [IA64] | IA64 build and utility area | [INSTALL] | installation, update and security procedures | [LOCAL] | site configuration files | [LOG] | site access logs | [LOG_SERVER] | server process (SYS$OUTPUT) logs | [RUNTIME] | graphics, help files, etc. | [SCRATCH] | working file space for scripts | [SCRIPT] | example architecture-neutral scripts | [SRC] | package source files | [STARTUP] | package startup procedures | [VAX-BIN] | VAX executable script files | [VAX] | VAX build and utility area

###
4.5 - 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 UNZIPping the package do the following:

      $ SET DEFAULT device:[HT_ROOT]
      $ @INSTALL

It performs the following tasks:

1. Build Executables - Either compile sources and link, or just link package object code to produce images for the local version of VMS. If the system has a suitable SSL toolkit the installer is requested whether an SSL enabled version be built.

2. Check Package - Executes a procedure that runs up the HTTPd in demonstration mode. Allows evaluation/checking of the basic package (4.7 - Quick-Check).

3. Create Server and Scripting Accounts - Create two, independent accounts, one for executing the server, the other for executing scripts (5.1 - VMS Server Account). If quotas are enabled on the target disk provides an ambit allocation for these accounts. Review this at some stage.

4. Set Package Security - This section traverses the newly installed tree and sets all package directories and files to required levels of access. For directory settings see 7.1 - Recommended Package Security.

5. Copy Support and Configuration Files - Copy the example server support and configuration files (5.3 - Account Support Files).

6. Install Scripts - Selectively copy groups of scripts from package build directories into the scripting directories.

Support files to consider when customizing startup, etc. (see 5.3 - Account Support Files for further detail):

  STARTUP.COM
  STARTUP_LOCAL.COM
  STARTUP_SERVER.COM

###
4.6 - Update DCL Procedure

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 UNZIPping the updated package do the following:

      $ @UPDATE

It provides the following functions:

1. Build Executables - Either compile sources and link, or just link package object code to produce images for the local version of VMS. If the system has a suitable SSL toolkit the installer is requested whether an SSL enabled version be built.

2. Server Quick-Check - Executes a procedure that runs up the HTTPd in demonstration mode. Allows evaluation/checking of the basic package (4.7 - Quick-Check).

3. Server Support/Configuration Files - Copies changed example HTTP server configuration and support files from the [EXAMPLE] directory to the [HTTP$SERVER], [LOCAL] and [STARTUP] directories.

4. Update Scripts - Selectively copy groups of scripts from package build directories into the scripting directories.

5. Reapply Package Security - This section traverses the updated tree and sets all package directories and files to required levels of access. For directory settings see 7.1 - Recommended Package Security.

6. Post-Update Cleanup - Prompts for permission to execute the post-update procedure described below.

7. Purge Files - Prompts for permission to purge the entire HT_ROOT:[000000...] tree.

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.7 - 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 its 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_24 spawned
      %DCL-S-ATTACHED, terminal now attached to process SYSTEM_24
      %HTTPD-I-SOFTWAREID, HTTPd-WASD/8.5.0 OpenVMS/AXP
      WASD VMS Hypertext Services, Copyright (C) 1996-2004 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, 02-JAN-2004 21:53:09
      %HTTPD-I-SYSTEM, Digital AlphaStation 500/333 VMS V7.3-2
      %HTTPD-W-SYSPRV, operating with implicit SYSPRV (UIC group 1)
      %HTTPD-I-TCPIP, Compaq TCPIP$IPC_SHR V5.4-15 (18-SEP-2003 21:58:05.32)
      %HTTPD-I-MODE, INTERACTIVE
      %HTTPD-I-ODS5, supported by Alpha VMS V7.3-2
      %HTTPD-I-GMT, +10: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-I-SCRIPTING, as HTTP$NOBODY
      %HTTPD-I-DCL, subprocess scripting
      %HTTPD-I-ACTIVITY, created global section of 816 page(let)s
      %HTTPD-I-SERVICE, http://klaatu.local.org: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, 02-JAN-2004 21:53:10, accepting requests

When http://the.host.name:7080 is accessed the browser should display something resembling

           == / \           Welcome. This page provides some basic
         /W A S D\          information on, and access to, the
      Empowered by VMS      "WASD VMS Hypertext Services"
         \/---\__/          package version 8.5
               ==

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

###
4.8 - "Clone" Procedure

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.9 - 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.6 - Update DCL Procedure.

###
4.10 - 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.11 - 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.12 - Local Setup Suggestions

Package updates will never contain anything in these directories:

  HT_ROOT:[HTTP$NOBODY]
  HT_ROOT:[HTTP$SERVER]
  HT_ROOT:[LOCAL]
  HT_ROOT:[STARTUP]

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.13 - 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 (19 - 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.au

Should the above address present problems or provide no response for an extended period then use
Mark.Daniel@dsto.defence.gov.au

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