|1Other Ways to Deploy| |^ While |/vanilla| installations provide a straight-forward and complete WASD package there a number of other approaches to the installation and maintenance of a site or sites. |2Server Environments| |^ WASD server environments allow multiple, distinctly configured environments to execute on a single system. Generally, WASD's unlimited virtual servers and multiple account scripting eliminates the need for multiple execution environments to kludge these requirements. However there may be circumstances that make this desirable; regression and forward-compatibility testing comes to mind. |^ First some general comments on the design of WASD. |bullet| |item| WASD creates and populates it's own logical name table (see |link|Logical Names||). |^ It also adds the WASD_FILE_DEV[|/n||] and WASD_ROOT[|/n||] logical names to the SYSTEM logical name table. |item| WASD creates and uses rights identifiers. |^ Installation creates and associates specific rights identifiers with separate accounts for server and script execution. Some specifically named identifiers have functional meaning to the server. Server startup can create and associate rights identifers used to manage the server run-time environment. |^ All executing server images are aware of all other executing server images on the same system and within the same cluster. This performs all manner of coordination (e.g. instance recovery, instantiated services) and data exchange (e.g. $HTTPD/DO=MAP/ALL) activities. |item| WASD uses global sections to accumulate data and for communication between WASD instances. |^ Some of these are by default permanent and remain on a system unless explicitly removed. |item| WASD uses detached scripting processes. |^ As it's possible to $STOP a server process (and thereby prevent it's run-down handlers from cleaning up those detached processes). It therefore needs to be able to recognise as its 'own' and clean any such 'orphaned' processes up next time it starts. It does this by having a rights identifier associated with the server process name (e.g. WASD:80 grants its scripting processes WASD_PRC_WASD_80, a second instance WASD2:80, WASD_PRC_WASD2_80, etc.) |!bullet| |^ All of these mechanisms support multiple, independent environments on a single system. Due to design and implementation considerations there are fifteen such environments available per system. The primary (default) is one. Environments two to fifteen are available for site usage. (Demonstration mode, /DEMO uses environment zero.) Server |/instances| (|link%|../features/##Server Instances++section in++WASD Features| document) share a single environment. |^ There are two approaches to provisioning such multiple, independent environments. |3Ad Hoc Server Wrapper| |^ This is a DCL procedure that allows virtually any WASD release HTTP server to be executed in a detached process, either by itself or concurrently with a full release or other ad hoc detached server. The server image and associated configuration files used by this process can be specified within the procedure allowing completely independent versions and environments to be fully supported. |^ Full usage instructions may be found in the example procedure(s) in |link%|/wasd_root/example/*adhoc*.*|WASD_ROOT:[EXAMPLE]*ADHOC*.COM|| |^ Two versions are provided, one for pre-v10 and one for post-v10 (due to changes in logical naming schema). |3Formal Environments| |^ Although the basic infrastructure for supporting multiple environments (i.e. the 0..15 environment number) has been in place since version 8, formal support in server CLI qualifiers and DCL procedures has only been available since version 10. To support version 9 or earlier environments the |link|Ad Hoc Server Wrapper| must be used. |^ WASD version 10 startup and other run-time procedures have been modified to support running multiple WASD environments simply from independent WASD file-system trees. The standard |link%|/wasd_root/example/startup.com|STARTUP.COM| procedure accepts the WASD_ENV parameter to specify which environment (1..15) the server should execute within (primary/default is 1). The procedure then derives the WASD_ROOT logical name from the location of the startup procedure. |^ For example: |code| $! start current release $ WASD_STARTUP = "/SYSUAF=(ID,SSL)/PERSONA" $ @DKA0:[WASD_ROOT.STARTUP]STARTUP.COM $! start previous release in environment 2 $ WASD_ENV = 2 $ @DKA0:[WASD_ROOT_MINUS1.STARTUP]STARTUP.COM |!code| |3Considerations| |^ WASD environments each fully support all WASD features and facilities (including multiple server instances) with the exception of DECnet scripting where because of DECnet objects' global (per-system) definition only the one must be shared between environments. |^ Per-environment configuration must be done in its own WASD_ROOT part of the file-system and logical names must be defined in the environment's associated logical name table. The site administrator must keep track of which environment requires to be accessed from the command-line and set the process logical name search list using the appropriate |code| $ @WASD_FILE_DEV|/[n]|| |!code| where |/n| can be a non-primary environment number (see |link|Logical Names||). |^ It is not possible to have multiple environments bind their services to the same IP address and port (for fundamental networking reasons). Unless the network interface is specifically multi-homed for the purpose, services provided by separate environments must be configured to use unique IP ports. |^ Non-primary environments (2|...|15) prefix the environment as a (hex) digit before the "WASD" in the process name. The above example when executing, each with a single scripting process, would appear in the system as (second environment providing a service on port 2280): |code| Pid Process Name State Pri I/O CPU Page flts Pages 00000101 SWAPPER HIB 16 0 0 00:00:11.98 0 0 |...| 00000111 ACME_SERVER HIB 10 6247 0 00:00:12.63 540 611 M 00000112 QUEUE_MANAGER HIB 10 328 0 00:00:00.18 136 175 00000122 TCPIP$INETACP HIB 10 1249419 0 00:07:33.95 401 326 00000123 TCPIP$ROUTED LEF 6 3495839 0 00:01:15.49 166 165 S |...| 00000468 WASD:80 HIB 6 132924 0 00:01:29.26 17868 2856 0000046D 2WASD:2280 HIB 6 129344 0 00:01:29.26 17712 2840 0000049D WASD:80-8 LEF 4 4449 0 00:00:00.67 934 194 00000503 2WASD:2280-2 LEF 4 565 0 00:00:00.28 732 102 |...| |!code| |0Cleaning Up| |^ As described earlier each environment creates and maintains logical name table(s) and system-level name(s), detached scripting processes, lock resources and permananent global sections. Lock resources disappear with the server processes. Logical names, global sections, rights identifiers and occasionally detached scripting processes may require some cleaning up when a non-primary environment's use is concluded. |2Multiple 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: |bullet| |item| 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). |code| $ SET DEFAULT device:[000000] $ UNZIP -d [.BLAH] device:[dir]archive.ZIP |!code| Do the same with object module archive(s) if required. |item| For the WASD OpenSSL package the WASD_ROOT portion of the tree must additionally be specified. |code| $ UNZIP -d [.BLAH.WASD_ROOT] device:[dir]OPENSSLWASD|/nnn-arch||.ZIP |!code| |item| 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. |code| $ RENAME [.BLAH]WASD_ROOT.DIR []WASD_ROOT_|/nnnn||.DIR $ DELETE BLAH.DIR;* |!code| |item| Move into the just renamed directory and build using the parameter INSTALL. |^- The build is (always) performed using locally defined logical names. |code| $ SET DEFAULT [WASD_ROOT_|/nnnn||] $ @INSTALL INSTALL |!code| |^ The INSTALL parameter overrides the install check and advisory message otherwise generated: |code| ***************************************** * "WASD_ROOT" LOGICAL NAME DETECTED. * * THIS DOES NOT LOOK LIKE AN INSTALL! * ***************************************** |!code| |item| As appropriate, copy configuration and other files from the current WASD installation to the new. |^- Check release notes for any variants. |code| $ COPY WASD_ROOT:[LOCAL]*.* [WASD_ROOT_|/nnnn||.LOCAL] |!code| |^ Other site-specific localisations similarly may need to be copied or otherwise reproduced. |^- For example, server or scripting account LOGIN.COM, scripts, etc. |!bullet| |^ To move the running WASD environment from one installation to another: |bullet| |item| Shut down the currently running server. |code| $ HTTPD/DO=EXIT=NOW |!code| |item| Start the desired version of WASD from its file-system location. |code| $ @device:[WASD_ROOT_|/nnnn||.STARTUP]STARTUP.COM |!code| |^ WASD logical names and environment will reflect the particular WASD root directory. |^- Site-specific elements in the startup might need to be similarly flexible. |!bullet| |99DCL Procedure SELECT.COM| |2SELECT.COM Procedure| |^ The |link%|/wasd_root/install/select.com|WASD_ROOT:[INSTALL]SELECT.COM| procedure allows a selective update to the most recent version from an earlier version, usually but not exclusively the previous version. Where there is some advantage in only updating part of the package this procedure can be used. |code| $ SET DEFAULT WASD_ROOT:[INSTALL] $ @SELECT DKA100:[WASD]WASD1150.ZIP WASD VMS Web Services, Copyright (C) 1996-2020 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 3, or any later version. http://www.gnu.org/licenses/gpl.txt ************************************* * SELECTIVELY UPDATE FROM ARCHIVE * ************************************* This procedure provides a site UPDATE using a full archive as the source. It examines the currently installed package to determine the relationship between the site and the archive. It then selectively extracts required files to bring the site up to revision. It can be used with full source archives as well as the optional object module archives. Each full archive is released with an increment in at least the tweak-level digit in the version string (.. e.g. "11.0.0") so this is used to determine the base-level installation of the current site. If for some reason this is not a standard site then do not use this procedure. Continue? [NO]: y *************************** * CHECK CURRENT VERSION * *************************** This selective update is to 11.5.0 This site has been determined to be 11.4.0 If this is not accurate then do not continue! ************************ * UPDATE FROM 11.4.n * * -or- 11.3.n * ************************ DKA100:[000000]WASD_ROOT.DIR;1 13-APR-2020 01:14:42.25 DKA100:[WASD]WASD1150.ZIP;1 9-JUL-2020 15:53:47.19 Continue? [NO]: |!code| |^ When extracted, the content can then be built using |=.@[.WASD_ROOT.INSTALL]UPDATE.COM| as described in |link|UPDATE.COM procedure||. It may or may not require a full update build. The procedure will advise if a specific portion can be more quickly built and deployed. |2.0\̷BTAIN.COM Procedure| |99.0BTAIN.COM Procedure| |99.OBTAIN.COM Procedure| |09DCL Procedure 0\̷BTAIN.COM| |^ |*&font-size:110%;.Yes |--| that's a ZERO!| |^ The |link%|/wasd_root/install/0btain.com|WASD_ROOT:[INSTALL]0\̷BTAIN.COM| procedure assists in installing and updating selected portions of a WASD package allowing a "bare-bones" site to be created. |^ An example use of the procedure looks something like: |code| $ SET DEFAULT DKA200:[000000] $ @WASD_ROOT:[INSTALL]0BTAIN DKA100:[WASD]WASD1150.ZIP WASD VMS Web Services, Copyright (C) 1996-2020 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 3, or any later version. http://www.gnu.org/licenses/gpl.txt *********************************** * WASD VMS Web Services v11.5.0 * *********************************** This DCL procedure allows elements of the above version of the WASD package to be extracted and installed/updated in a selective manner. It does require some knowledge of the WASD package and sometimes significant manual intervention. It is intended to allow a site to tailor the WASD content of the installation. Press RETURN to continue: The WASD_ROOT directory is always assumed to be a subdirectory of the current directory and is always created if not already existing. Always perform @0BTAIN from the parent of the (desired) [.WASD_ROOT] even when updating. There is currently no [.WASD_ROOT] in the current directory. Any further action will result in the creation of one. Continue? [NO]: y The selection can be made by specifying one of the listed elements, or by archive path. An overview will be presented and continuing with the option can be declined before continuing. If declined an option to display what would have been extracted is available. If an object module archive is present along with the primary archive the relevant modules are also extracted. 1. CORE extracts build, server, monitor, documentation 2. INSTALL extracts install environment 3. SERVER extracts server code 4. WASDOC extracts documentation and wasDOC code 5. SCRIPTS extracts essential scripts 6. path archive path (e.g. "wasd_root/src/httpd/*") 0. exit Number or string? [0]: |!code| |^ When extracted, the content of the new |=.[.WASD_ROOT]| directory can then be built using |=.@[.WASD_ROOT.INSTALL]INSTALL.COM| as described in |link|INSTALL.COM procedure||, or |=.@[.WASD_ROOT.INSTALL]UPDATE.COM| as described in |link|UPDATE.COM procedure||, as appropriate. When using these procedures individual sections building non-extracted elements must be declined. Alternatively, the build procedures associated with individual elements may be directly used. |^ The latest version of the procedure is automatically extracted from the specified package, or it manually can be extracted from the target package archive using |code| $ SET DEFAULT |/parent_device||:[|/parent_directory||] $ UNZIP -jl |/location:archive||.ZIP "*/0btain.com" !(just to check) $ UNZIP -j |/location:archive||.ZIP "*/0btain.com" $ @[]0BTAIN.COM |!code| |^ When manually extracted as above, the final stage of the procedure will report |code| **************************************************************** * - IGNORE THE FOLLOWING - * * %RMS-E-FNF, file not found * * %RMS-F-ISI, invalid internal stream identifier (ISI) value * **************************************************************** |!code| which can be safely ignored (the procedure deletes itself from the extracted-to directory which results in the DCL interpreter reporting the disappearance of the file). |^ Alternatively, if the latest package has been extracted to a local location, or a previous installation included [INSTALL]0BTAIN.COM, then that version can be used to start the whole thing off, extracting the relevant 0BTAIN.COM from the specified archive and then executing it. |99DCL Procedure CLONE.COM| |2CLONE.COM Procedure| |^ The |link%|/wasd_root/install/clone.com|WASD_ROOT:[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. |^ An example use of the procedure looks something like: |code| $ @WASD_ROOT:[INSTALL]CLONE WASD VMS Web Services, Copyright (C) 1996-2020 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 3, or any later version. http://www.gnu.org/licenses/gpl.txt *********************** * CLONE THE PACKAGE * *********************** This utility creates a separate DCL procedure containing ZIP commands to archive specified portions of the current system's WASD_ROOT:[000000] tree. That procedure can then be executed to create an archive which may then be UNZIPed on any other system(s) to create a copy of the original. In this way multiple WASD packages can be deployed without going through the full installation process and using the original as a working template. Some portions of the package are essential to any working installation. These are always archived. Others are prompted for and commands to archive those are only added to the procedure if required. Multiple such procedures may be created by specifying unique archive procedure names. Create a cloning procedure? [NO]: y ************************ * DCL PROCEDURE NAME * ************************ If multiple cloning procedures are required enter a specific file name, otherwise use the default. DCL procedure? [CLONE_WASD.COM]: ****************** * ARCHITECTURE * ****************** Executables for multiple architectures ([AXP], [IA64], [X86_64]) detected. Add [AXP] executables? [NO]: y Add [IA64] executables? [NO]: n Add [X86_64] executables? [NO]: n Continue? [NO]: y *************** * ESSENTIAL * *************** These directories and files are essential and always included: [AXP] HTTPD.EXE HTTPD_SSL.EXE HTTPDMON.EXE SECHAN.EXE [AXP-BIN] Alpha script executables [CGI-BIN] architecture-neutral script files [HTTP$NOBODY] server account home [HTTP$SERVER] scripting account home [INSTALL] installation, update and security procedures [LOCAL] local configuration files [LOG] access logs [LOG_SERVER] server process logs [RUNTIME.HTTPD] server runtime files (directory listing graphics, etc) [SCRATCH] scripting scratch space [STARTUP] startup procedures (STARTUP*.COM) Most directories retain some files (e.g. .WWW_HIDDEN, READMEs) but are only optionally populated with other files as requested. Continue? [NO]: y ******************* * CONFIGURATION * ******************* Files from [LOCAL]*.conf (e.g. HTTPD$CONFIG, HTTPD$MAP, etc.) Add? [NO]: y ************* * SCRIPTS * ************* Files from [CGI-BIN] and executables from [AXP-BIN] and/or [IA64-BIN] and/or [X86_64-BIN]. Note that this adds ALL files from these directories. Of course you can manually edit the resultant procedure to remove unwanted items. This also adds the rest of the files from the [RUNTIME...] directory tree (remembering that [RUNTIME.HTTPD] is included with the essential files). Add? [NO]: n ******************* * DOCUMENTATION * ******************* Files from [WASDDOC...]*.* Add? [NO]: y ************************ * EXAMPLE & EXERCISE * ************************ Files from [EXAMPLE]*.* and [EXERCISE]*.*. Add? [NO]: n ************ * SOURCE * ************ Files from [SRC...]*.*. Add? [NO]: n ******************************** * CREATING ARCHIVE PROCEDURE * ******************************** Created WASD_ROOT:[install]CLONE_WASD.COM;1 The contents of this procedure can be manually modified and/or other command lines added to archive or remove specific areas and/or files. ********************* * C O M P L E T E * ********************* |!code|