WASD Install and Update

1.New to WASD? Start Here!

Welcome!

WASD is outlined in the Introduction and Package Overview sections of the WASD Features document.

There are a number of approaches to installing and updating a WASD package.
The vanilla recipes are 2. Installation and 3. Update but there are 5. Other Ways to Deploy.

This section provides a quick guide to getting your WASD package installed, configured and serving.

1. Unzip Package

   Install the files following the guidelines in 2. Installation.
   Note that more than one archive may be needed (‘Source Archive, Object Module Archives’ in 2.1 Package UNZIP).

   If Transport Layer Security (TLS - a.k.a. Secure Sockets Layer - SSL) is to be used and a TLS/SSL server image to be built the WASD [Open]SSL product must be installed at this stage (see TLS/SSL Functionality Sources of WASD Features and Facilities). An existing VSI SSL111 for OpenVMS product (all based on OpenSSL 1.0.2 and earlier obsolete) requires no additional step. If the WASD [Open]SSL package it must UNZIPed into the [.WASD_ROOT] tree at this stage.

   $ UNZIP -d [.WASD_ROOT] device:[dir]OPENSSLWASDnnn-arch.ZIP

   Note the use of the "-d" switch.

2. INSTALL Package

   Server installation is performed using the INSTALL.COM procedure (2.9 INSTALL.COM Procedure).

   • Build Package – Compile and link, or just link supplied object files to produce VMS executables for the system's version of VMS.
   • Check Package – Check basic operation of the package (2.10 Quick-Check).
   • Create Server and Scripting Accounts – Create two independent accounts, one for executing the server, the other for executing scripts (4.1 VMS Server Account). If quotas are enabled on the target disk provides an ambit allocation for these accounts. Review this at some stage.
   • Set Package Security – This sections traverses the newly installed tree and sets all package directories and files to required levels of access (Maintaining Package Security in WASD Configuration).
   • Copy Support and Configuration Files – Copy the example server support and configuration files (4.3 Account Support Files).
   • Install Scripts – Selectively copy groups of scripts from package build directories into the scripting directories.
3. Configure Package

   Following the execution of the INSTALL.COM procedure the package should require only minor, further configuration.

   Initially two files may require alteration.

   1. The startup file, possibly to set the local WASD_CONFIG_GMT logical (for systems not supporting DTSS (e.g. DECnet-Plus)). Consider using the STARTUP_LOCAL.COM file for other site-specific requirements (4.3 Account Support Files).
   2. The only configuration that should require immediate attention will be the mapping rules (Request Processing Configuration in WASD Configuration).

   More generally server runtime configuration involves the considerations discussed in Site Organisation of WASD Configuration along with the following aspects:

   • Configuring the HTTP server run-time characteristics (Configuration Considerations in WASD Configuration).
   • Mapping request paths to the VMS file system, and to other things such as scripts (Request Processing Configuration in WASD Configuration).
   • Customizing some or all messages (Message Configuration in WASD Configuration).
   • Establishing an authentication and authorization environment (Authorization Configuration (Basics) in WASD Configuration).
4. Start Server

   Execute the startup procedure (‘STARTUP.COM’ in 4.3 Account Support Files). Get your browser and connect!

5. Find Out What's Wrong  

   Of course something will not be right! This can happen with the initial configuration and sometimes when changing configuration. The server provides information messages in the run-time log, look in the WASD_ROOT:[LOG_SERVER] directory.

   Remember, the basic installation's integrity can always be checked as described in 2.10 Quick-Check). This uses the configuration files from the [EXAMPLE] directory, so provided these have not been altered the server should execute in demonstration mode correctly.

   Can't resolve it? See 2.12 Reporting Problems.

1.1Using IA64-hosted X86 Cross-Complier?

Until a native X86 C compiler becomes available all WASD package and additional application builds must be done in two phases.

1. cross-compile on an IA64 system
2. link resulting object file(s) on the X86 system

When building using the cross-compiler tools the procedures recognise the XCC$COMPILER environment and adjust to create and use [.OBJ_X86_64] object code directories.

For example; to build WASD package:

1. On IA64 ensure @SYS$MANAGER:X86_XTOOLS$SYLOGIN.COM and then select "3. Compile only" and complete the compilation.
   • For clustered IA64/X86 with an MSCP-mounted volume containing a shared [WASD_ROOT] the appropriate object files are now available to the X86 system.

     Proceed with the second phase.

   • For non-clustered build environments the same WASD kit must be installed on both IA64 and X86 systems. After compilation the resulting [.OBJ_X86_64] directories must be ZIPed into an archive, transferred to the X86 system and restored into the corresponding [WASD_ROOT].

     For example:

     IA64$ SET DEFAULT device:[WASD_ROOT] IA64$ ZIP "-V" location:X86_1200_OBJ.ZIP [...OBJ_X86_64]*.OBJ
     X86$ SET DEFAULT device:[WASD_ROOT] X86$ UNZIP location:X86_1200_OBJ.ZIP

     Proceed with the second phase.

2. On X86 perform the corresponding "2. linking (separate package) object modules", and continue the rest of the installation.

1.2Troubleshooting?

When initially installing or configuring WASD, and sometimes later where something breaks spectacularly, it is most useful to be able to gain insight into what the server is up to.

The go-to tool is  WATCH  (yes, all capitals, and for no other reason than it makes it stand out).

WATCH is described in detail in WATCH Facility of the WASD Features and Facilities document.

For most circumstances WATCH can be made available for troubleshooting even if the configuration is significantly broken. This is done by using a skeleton-key to authorise special access into the server.

The skeleton-key is described in detail in Skeleton-Key Authentication of the WASD Features and Facilities document.

TL;DR

Enable at the command-line with the username anything beginning with an underscore and at least 8 characters, same for the password length.

Then using a browser access any available service, entering the above username (including underscore) and password when prompted.

The service administration facilities (of which WATCH is one) are also available and useful.