WASD Installation and Configuration

2.Installation and Update

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

The ZIP archive will contain brief installation instructions. Use the following command to read this and any other information provided.

It is recommended to check the integrity of, then list the contents of, the archive before UNZIPing.

The archive will have the structure:

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

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 v6.n or greater).

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.

WASD OpenSSL Archive

Building an SSL-capable version of the server is a common requirement. WASD SSL is discussed in detail in Transport Layer Security of WASD Features and Facilities. and if using the WASD SSL package it is also possible to install (or update) that package after UNZIPing the primary archive and optional object module(s). As noted in the above SSL section, the server can also be built against an existing VMS SSL product and an existing OpenSSL installation.

Existing Installations

When installing an archive as an update to 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 WASD_ROOT:[000000...] location:WASDROOT.BCK/SAVE/VERIFY $ ZIP "-V" location:WASDROOT.ZIP device:[WASD_ROOT...]*.* $ ZIP "-T" location:WASDROOT.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 device:[dir]archive-AXP.ZIP ht_root/src/httpd/obj_axp/*.*

Multiple Installations

Multiple, independent installations and builds of WASD are supported. See ‘Multiple Installations 2’  in  2.13 Multiple Installations later in this chapter.

2.2ODS-5 Volumes

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!)

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

2.4Package 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 (see 5.2 Recommended Package Security).

Package Directory Structure

2.5TCP/IP Infrastructure

The WASD installation assumes that the system's TCP/IP infrastructure is correctly installed and configured, and is operating normally. For example, it is not unknown for a freshly built system to experience host name resolution problems preventing its own host name from being resolved and making even elementary server startup impossible.

2.6SYSUAF and RIGHTSLIST

These behaviours must be considered in site environments where such changes are prohibited or closely controlled.

2.7Installation 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:

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. Note the possible UDFSYM described in 2.9 LINK-I-UDFSYM.
2. Check Package – Executes a procedure that runs up the HTTPd in demonstration mode. Allows
3. Create Server and Scripting Accounts – Create two, independent accounts, one for executing the server, the other for executing scripts (3.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 5.3 Maintaining Package Security.
5. Copy Support and Configuration Files – Copy the example server support and configuration files (3.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. (3.3 Account Support Files):

• STARTUP.COM
• STARTUP_LOCAL.COM
• STARTUP_SERVER.COM

2.8Update 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!

After UNZIPing the updated package do the following:

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. Note the possible UDFSYM described in 2.9 LINK-I-UDFSYM.
2. Server Quick-Check – Executes a procedure that runs up the HTTPd in demonstration mode. Allows evaluation/checking of the basic package (2.10 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 5.2 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 WASD_ROOT:[000000...] tree.

If declined during the update procedure the post-update steps 6 and 7 can be performed at any subsequent time using

2.9LINK-I-UDFSYM

Linking the server code against older versions of OpenSSL (less likely) or the HP SSL product (more likely, V1.4 for instance) will result in the reporting of one, two or three undefined symbols (usually one or two as shown below).

Any of these three reports may safely be ignored as the server is designed to detect the absence and disable the related functionality.

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

When http://the.host.name:7080 is accessed the browser should display the package home page

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

2.12Re-Linking

After a major update to the operating system the package may refuse to start, reporting a message like:

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, 2.8 Update DCL Procedure.

Multiple Installations 2

2.13Multiple Installations

It is possible, and often useful, to build another WASD on a system with an existing and/or running installation. One purpose might be to maintain the previous version as a fallback in case of unexpected problems when migrating to a more recent version. Another, to maintain multiple releases for regression testing.

The general process is as follows:

• A clash with any existing [WASD_ROOT] directory must be avoided.
  Using the "-d" switch, UNZIP into a working directory using any unique name (BLAH in this example).
  $ SET DEFAULT device:[000000] $ UNZIP -d [.BLAH] device:[dir]archive.ZIP
  Do the same with object module archive(s) if required.
• For the WASD OpenSSL package the WASD_ROOT portion of the tree must additionally be specified.
  $ UNZIP -d [.BLAH.WASD_ROOT] device:[dir]OPENSSLWASDnnn-arch.ZIP
• Rename the WASD root directory into the current directory using a representative name (appending the version number is suggested) and then delete the working directory.
  $ RENAME [.BLAH]WASD_ROOT.DIR []WASD_ROOT_nnnn.DIR $ DELETE BLAH.DIR;*
• Move into the just renamed directory and build using the parameter INSTALL.
  The build is (always) performed using locally defined logical names.
  $ SET DEFAULT [WASD_ROOT_nnnn] $ @INSTALL INSTALL

  The INSTALL parameter overrides the install check and advisory message otherwise generated:

  ***************************************** * "WASD_ROOT" LOGICAL NAME DETECTED. * * THIS DOES NOT LOOK LIKE AN INSTALL! * *****************************************
• As appropriate, copy configuration and other files from the current WASD installation to the new.
  Check release notes for any variants.
  $ COPY WASD_ROOT:[LOCAL]*.* [WASD_ROOT_nnnn.LOCAL]

  Other site-specific localisations similarly may need to be copied or otherwise reproduced.
  For example, server or scripting account LOGIN.COM, scripts, etc.

To move the running WASD environment from one installation to another:

• Shut down the currently running server.
  $ HTTPD/DO=EXIT=NOW
• Start the desired version of WASD from its file-system location.
  $ @device:[WASD_ROOT_nnnn.STARTUP]STARTUP.COM

  WASD logical names and environment will reflect the particular WASD root directory.
  Site-specific elements in the startup might need to be similarly flexible.

2.14VMS 6.n

As of WASD v10.1 the minimum supported version for build and operation is VMS V7.0. Had to drag ourselves into the mid-1990s at some stage!

2.15VMS 5.5-n

WASD does not build or run under VMS 5.5-2 or earlier.

2.16Local Setup Suggestions

Package updates will never contain anything in these directories:

• WASD_ROOT:[HTTP$NOBODY]
• WASD_ROOT:[HTTP$SERVER]
• WASD_ROOT:[LOCAL]
• WASD_ROOT:[STARTUP]

To prevent the overwriting of local configuration files it is suggested these be placed in the WASD_ROOT:[LOCAL] directory. Local authentication databases could also be placed in the [LOCAL] directory. Startup files can be placed where the local site manages system startup. These could be placed in the WASD_ROOT:[STARTUP] directory.

2.17Reporting 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 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