NOTE: SOME FUNCTIONALITY EMPLOYS JAVASCRIPT WASD Install and Update – Installation

WASD Install and Update

2.Installation

2.1Package UNZIP
2.2Package Directory Structure
2.3ODS-5 Volume
2.4Accessible Volume
2.5Disk Quota
2.6VMS 6.n
2.7SYSUAF and RIGHTSLIST
2.8TCP/IP Infrastructure
2.9INSTALL.COM Procedure
2.10Quick-Check
2.11Local Setup Suggestions
2.12Reporting 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:

KLAATU$ unzip -l dka100:[WASD]wasd1200.zip;1 Archive: DKA100:[WASD]wasd1200.zip;1 Copyright (C) 1996-2021 Mark G.Daniel Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. * FULL RELEASE of v12.0.0 (1 November 2021) ************************************************** *** 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]WASD1200.ZIP * To build/link images use the appropriate one of: $ @device:[WASD_ROOT]INSTALL $ @WASD_ROOT:[000000]UPDATE * Contains build refinements to ease cross-compiling for x86-64 VMS. VMS file attributes saved ... use UnZip 5.2+ on OpenVMS Archive created 1-NOV-2021 Length Date Time Name -------- ---- ---- ---- 0 10-24-21 09:04 wasd_root/axp-bin/ 0 10-24-21 09:04 wasd_root/axp/ 0 10-24-21 09:04 wasd_root/cgi-bin/ 0 10-24-21 09:04 wasd_root/doc/ 0 10-24-21 09:04 wasd_root/example/ 0 10-24-21 09:04 wasd_root/exercise/ 2734 03-06-03 17:20 wasd_root/favicon.ico 8< snip 8< 40221 10-04-21 21:37 wasd_root/wasdoc/scripting/scripting012.html 18156 10-04-21 21:37 wasd_root/wasdoc/scripting/scripting013.html 442 09-21-20 12:13 wasd_root/x86_64-bin/readme.html 464 09-20-20 10:10 wasd_root/x86_64/readme.html -------- ------- 23868969 1009 files

2.1Package UNZIP

While an elementary installation involves a simple UNZIP into a parent directory, take a moment to consider the future and later update versions. Keep server and site resources independent. This will make updates much simpler. Also consider ‘Multiple Installations’ in 5.1.3 Considerations.

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] $ 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 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 X86, 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 site architecture must be UNZIPed 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-X86.ZIP
Note

The WASD distribution and package organisation fully supports mixed-architecture clusters (AXP, Itanium and/or x86-64 in the one cluster) as one integrated installation.
WASD OpenSSL

Building an SSL-capable version of the server is a common requirement.

As described in VSI OpenSSL SSL111-V0101-1S and SSL3-V0300-7 it is now possible to install VSI OpenSSL releases on pre-V8.4 VMS. This is the recommended approach to providing and maintaining OpenSSL for WASD.

WASD SSL is discussed in detail in Transport Layer Security of WASD Features and Facilities.

2.2Package 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 Recommended Package Security in WASD Configuration).

Package Directory Structure

Directory Description
[AXP-BIN] Alpha executable script files
[AXP] Alpha build and utility area
[CGI-BIN] architecture-neutral script files
[EXAMPLE] package examples
[EXERCISE] package test files
[HTTP$NOBODY] scripting account default home area
[HTTP$SERVER] server account default home area
[IA64-BIN] Itanium executable script files
[IA64] Itanium 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
[WASDOC] package documentation
[X86_64-BIN] x86-86 executable script files
[X86_64] x86-64 build and utility area

2.3ODS-5 Volume

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.4Accessible 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 DKA100: ALPHASYS object of class VOLUME Owner: [1,1] Protection: (System: RWCD, Owner: RWCD, Group: RWCD, World: RWCD) Access Control List: <empty>

2.5Disk Quota

Should WASD_ROOT be located on a volume with disk quota enabled then suitable entries must exist for the server account (default HTTP$SERVER), SYSTEM account, and any scripting account(s) (default HTTP$NOBODY). The server account requires quota for the server process log, SYSTEM (due to SYSPRV use) for access log(s), and scripting account(s) requiring default temporary storage ([SCRATCH]) during processing.

2.6VMS 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.7SYSUAF and RIGHTSLIST

WARNING!

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.


2.8TCP/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.

DCL procedure INSTALL.COM

2.9INSTALL.COM 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:[WASD_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 the server build to be verified.
  3. 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.
  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 Maintaining Package Security in WASD Configuration.
  5. Copy Support and Configuration Files – Copy the example server support and configuration files (4.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. (4.3 Account Support Files):

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.

If a TLS (SSL) -enabled server has been built the demonstration server will also provide a TLS port number 7443 for access (this also can be explicitly activated using @[INSTALL]DEMO.COM SSL). WASD will dynamically generate a X509 certificate for use by the service. In modern browsers there are security constraints associated with self-signed certificates — lots! Interestingly, Incognito/[In]Private instances of a browser are often more relaxed about accepting certificates with security deficiencies (at least at the time of writing), so perhaps try those with the demonstration server. Also see Server Certificate in WASD Features.

X86VMS$ @wasd_root:[install]demo Copyright (C) 1996-2021 Mark G.Daniel ------------------------------------- Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. http://www.apache.org/licenses/LICENSE-2.0 ******************************* * WASD PACKAGE DEMONSTRATOR * ******************************* 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 either of the "%HTTPD-I-SERVICE"s when the server starts. (There will be one for a standard service and another for SSL.) 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)? []: testing %DCL-S-SPAWNED, process SYSTEM_32419 spawned %DCL-S-ATTACHED, terminal now attached to process SYSTEM_32419 %HTTPD-I-SOFTWAREID, HTTPd-WASD/12.0.0 OpenVMS/X86 SSL WASD VMS Web Services, Copyright (C) 1996-2021 Mark G.Daniel. Licensed under the Apache License, Version 2.0 (the "License"). Software under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See http://www.apache.org/licenses/LICENSE-2.0 %HTTPD-I-IMAGE, HTTPD_SSL 12.0.0 31-OCT-2021 07:38:27.62 DKA100:[wasd_root.][x86_64]HTTPD_SSL.EXE;1 %HTTPD-I-STARTUP, 01-NOV-2021 11:47:05 %HTTPD-I-ALIGN, start collecting alignment faults (64kB,128,0xFFFFFFFF) %HTTPD-I-WASD_ROOT, DKA100:[WASD_ROOT] %HTTPD-I-ENVIRONMENT, 0 %HTTPD-I-SYSTEM, innotek GmbH VirtualBox VMS V9.1-A %HTTPD-W-SYSPRV, operating with implicit SYSPRV (UIC group 1) %HTTPD-I-TCPIP, HP TCPIP$IPC_SHR X6.0-12 (31-AUG-2021 20:01:12.49) %HTTPD-I-MODE, INTERACTIVE %HTTPD-I-ODS5, supported by x86-64 VMS V9.1-A %HTTPD-I-ODS, directory parser enabled %HTTPD-I-GMT, +10:30 %HTTPD-I-INSTANCE, supervisor %HTTPD-W-GZIP, shareable image not found %HTTPD-I-INSTANCE, 1 process %HTTPD-I-SSL, OpenSSL 1.1.1k 25 Mar 2021 (0x101010BF) -SSL-I-PROTOCOL, TLSv1,TLSv1.1,TLSv1.2,TLSv1.3 -SSL-I-OPTIONS, 0x80410854 -SSL-I-SNI, Server Name Indication enabled -SSL-W-DH, no ephemeral DH param %HTTPD-I-HTTP2, enabled %HTTPD-W-HTTP2, network read buffer size increased to 16384 bytes %HTTPD-I-VM, HTTP/2 zone initialised %HTTPD-I-INSTANCE, process name WASD:7080 %HTTPD-I-WEBDAV, disabled %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-PROXYVERIFY, for 32 records in local storage of 14 page(let)s %HTTPD-I-SCRIPTING, as HTTP$NOBODY %HTTPD-I-VM, request zone initialised %HTTPD-I-DCL, subprocess scripting %HTTPD-I-DCL, with HTTP/2 enabled SYS$OUTPUT mailbox might be more efficient at 16375 bytes %HTTPD-I-VM, cache zone initialised %HTTPD-I-ACTIVITY, created global section of 1312 page(let)s %HTTPD-I-SERVICE, http://x86vms.lan:7080 %HTTPD-I-SERVICE, https://x86vms.lan:7443 %HTTPD-I-SSL, x86vms.lan:7443 Generate x86vms.lan 2048 bit private key: ...........................................+++++ ...........................................+++++ %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, 01-NOV-2021 11:47:09, WASD:7080 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.

2.11Local 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 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.12Reporting 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 or if a suscriber, to info-WASD@vsm.com.au.