WASD Hypertext Services - Technical Overview

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

4 - Installation and Update

The WASD package and updates will always be distributed as ZIP archives.

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

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]

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]

In either case it is recommended to check the integrity of, then list the contents of, the archive before UNZIPping. This may be done as follows:

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

A complete installation/update (the former) 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
     16384  07-30-97  09:21   ht_root/vax/wwwrkout_netlib.exe
    ------                    -------
  19109754                    996 files

An update (the latter) 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
     27136  07-30-97  09:21   axp/wwwrkout_netlib.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

The archive may then be UNZIPped. If this is a completely new installation a new directory tree will be created. If an update to an existing installation the tree will be created "over-the-top" of the existing structure.

When updating:


4.1 - 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 default to "no".

It performs the following tasks:

  1. Link Executables - Links the package object code to produce images for the local version of VMS.

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

  3. Directory Protections - This section checks for correct directory protection in the HT_ROOT:[000000] tree and prompts to change it to WORLD:RE if it appears incorrect.

  4. Create Server Account - Creates an unprivileged account for the HTTP server to execute within. Sets permissions on files and directories allowing appropriate access for this account.

  5. Disk Quota - Check if quotas are enabled on the target disk. Provide an ambit allocation for the server account. Review this at some stage.

  6. Server Support/Configuration Files - Copies example HTTP server configuration and support files from the [EXAMPLE] directory to the [HTTP$SERVER] and [LOCAL] directories. No copy is made without prompting for permission.

After UNZIPping the package do the following:

  $ SET DEFAULT device:[HT_ROOT]
  $ @INSTALL

NOTE:  The installation procedure provides a reasonable, vanilla, single-node set-up. If something different is required a little time and thought may be required further configuring startup, etc.

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


4.2 - 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 default to "no".

It provides the following functions:

  1. Link Executables - Links the package object code to produce images for the local version of VMS.

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

  3. Server Support/Configuration Files - Copies changed example HTTP server configuration and support files from the [EXAMPLE] directory to the [HTTP$SERVER] and [LOCAL] directories. This copy is made without prompting for permission.

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

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

After UNZIPping the updated package do the following:

  $ SET DEFAULT HT_ROOT:[000000]
  $ @UPDATE

Post-Update

When confident regarding the success of the update (these activities can be part of the update DCL procedure).


4.3 - Quick-Check

Once installed or updated it is possible to check the basic package at any time using the FREEWARE_DEMO.COM procedure. It should detect the TCP/IP agent in use (if not specify UCX or NETLIB as a parameter). Follow the displayed instructions.

  @device:[HT_ROOT]FREEWARE_DEMO

Problem? SYSTEM-F-SHRIDMISMAT? See next section!


4.4 - Re-Linking

After an 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.2 - Update DCL Procedure.


4.5 - Local Setup Suggestions

Package updates will never contain anything in these three directories:

To prevent the overwriting of local configuration files it is suggested these be placed in the HT_ROOT:[LOCAL] directory. Startup files will most probably be placed where-ever the local site manages system startup. These could be placed in the HT_ROOT:[LOCAL] directory if there is nowhere more appropriate. Authentication databases could also be placed in the [LOCAL] directory. The server account's support files (LOGIN.COM, etc.) may be copied from the HT_ROOT:[EXAMPLE] directory into HT_ROOT:[HTTP$SERVER] and customized as necessary.

In like manner, local DCL scripts or DCL wrappers for executable scripts should be placed in HT_ROOT:[SCRIPT_LOCAL]. Executables should continue to be placed in HT_EXE:

Changes that are made in package configuration files, etc., can then be propagated to the local areas as appropriate.


4.6 - Organizing Documents

It is recommended that the server distribution tree and any document and other Web-specific data areas be kept separate and distinct. The former in HT_ROOT:[000000], the latter in something like WEB:[000000]. This logical device could be provided with the following DCL introduced into the server startup procedures:

  $ DEFINE /SYSTEM /TRANSLATION=CONCEALED WEB DSA811:[WEB.]

The logical organisation of served data is largely hierarchical, organised under the Web-server path root, and is achieved via two mechanisms.

  1. The natural tree structure provided by a hierarchical file system.

  2. The logical hierarchy possible using rules within the mapping file to place disparate physical areas into a single logical structure (see 8 - Mapping Rules).

WASD has a single section of the file system for the core Web files, such as the Division home page, help areas, Web documentation, etc., it can be accessed using the logical device WEB:[000000]. Incorporated with this are other subdirectories providing storage for specific collections of data, such as committee minutes, administration announcements, etc.

Physically distinct areas are used for good physical reasons (e.g. the area can best be hosted on a task-local disk), for historical reasons (e.g. the area existed before any Web environment existed) or for reasons of convenience (e.g. lets put this where access controls already allow the maintainers to manage it).

Reasons for an area being physically integrated with the core Web data area can be legitimate (e.g. there is really nowhere else it reasonably belongs), convenience (e.g. let's quickly put it here) or by logical necessity (it really does below as part of the core Web enviroment, e.g. documentation on HTML, etc.)

Guidelines

In general, only Web-related files need to go into the core physical Web file area. All other groupings should, if possible, be decentralised into the portion of the file system they represent and logically placed in the server's path using rules in the mapping file. That is, a given project's Web files should be located in the project's part of the file system. If it doesn't have any then it may be a candidate for location in the core area.

When locating a Web area in a physically distinct area it is possible the maintainers of that data will already have the correct access controls. If locating an area in the core hypertext environment it will be necessary to give the mantainer ownership of the directory area (and possibly disk quota), or provide ACL access if multiple maintains are involved.

When locating Web-accessable data in a physically distinct area it will be necessary to update the mapping file with a new rule (see 8 - Mapping Rules). If located within the core Web area the rules do not need to be adjusted.


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

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@dsto.defence.gov.au.


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