WASD yahMAIL for VMS Apache (CSWS)

WASD yahMAIL for VMS Apache (CSWS)
May 2005, 1.8.3

WASD VMS Hypertext Services, Copyright © 1996-2005 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.

WASD yet another hyperMAIL provides direct, on-line Web access to a VMS system's native Mail environment via a standard browser. For further information see yahMAIL Usage Guide.

Installation

Development environment was CSWS V1.3. Installation steps:

THIS SCRIPT REQUIRES CAREFUL CONFIGURATION
read the yahMAIL Usage Guide thoroughly first!
build executable
- link-only:
  $ @BUILD_YAHMAIL MIME LINK
- alternatively COMPILE+LINK (requires DECC 5.n or 6.n):
  $ @BUILD_YAHMAIL MIME BUILD
- in a PMDF environment, to enable MIME uploads LINK:
  $ @BUILD_YAHMAIL MIME PMDF LINK
- alternatively COMPILE+LINK (requires above):
  $ @BUILD_YAHMAIL MIME PMDF BUILD
copy executable and support procedure
- initial installation:
  $ @INSTALL INSTALL APACHE
- subsequent update:
  $ @INSTALL UPDATE APACHE
yahMAIL script startup
- if server username is "APACHE$WWW":
  $ @APACHE$ROOT:[000000]YAHMAIL_STARTUP
- if server username is something else:
  $ @APACHE$ROOT:[000000]YAHMAIL_STARTUP username
add mapping and authorization rules as described in Configuration below
read configuration chapter of yahMAIL Usage Guide again then modify YAHMAIL$CONFIG against local requirements: $ EDIT YAHMAIL$CONFIG
It is possible to localize the language of the text and messages provided by yahMAIL. Check the file LANG_EN.C for details.

Configuration

The startup procedure must be executed at system startup or if the software is reinstalled or updated. Ensure this becomes part of the Web environment's startup.

For an VMS Apache installation the files are distributed as follows:

APACHE$COMMON:[CGI-BIN]YAHMAIL_AXP.EXE
APACHE$COMMON:[CGI-BIN]YAHMAIL_IA64.EXE
APACHE$COMMON:[CGI-BIN]YAHMAIL.COM
APACHE$COMMON:[CONF]YAHMAIL.CONF
APACHE$COMMON:[000000]YAHMAIL_STARTUP.COM
APACHE$COMMON:[SRC.WASD.DOC]

As discussed in the documentation, private access to user email requires authentication and authorization. Apache offers a number of mechanisms for authentication and authorization configuration. Please consult the relevant documentation. The following provides example [CONF]HTTPD.CONF entries for SYSUAF authentication.

  # YAHMAIL.CONF will need to have it's paths to the documentation edited!
  Alias /yahmail/doc/ "/apache$common/src/yahmail/doc/"
  
  #(if CSWS 1.3)
  LoadModule auth_openvms_module /apache$common/modules/mod_auth_openvms.exe_alpha
  #(if SWS 2.0, possibly later)
  ##LoadModule auth_openvms_module /apache$common/modules/mod_auth_openvms.exe

  <Location /cgi-bin/yahmail>
  AuthType Basic
  AuthName "OpenVMS authentication"
  AuthUserOpenVMS On
  require valid-user
  </Location>

Mark G. Daniel
Mark.Daniel@wasd.vsm.com.au
Mark.Daniel@dsto.defence.gov.au

Demonstration & Download
http://wasd.vsm.com.au/
http://wasd.vsm.com.au/wasd/
ftp://ftp.vsm.com.au/wasd/index.html ifier specifying the individual quota percentage, though this granularity of control should seldom be necessary. For example /QUOTA=(20,BYTLM:20,PGFLQUO:50) sets all quotas to a minimum of 20% but specifically sets BYTlm to 20% and Pgflquo to 50%. HTTP STATUSES ------------- The command-line /HTTP qualifier allows specified HTTP status groups to be monitored. Those available are 2xx, 3xx, 4xx and 5xx, although the only meaningful ones for such attention are the 4xx (not found, forbidden, etc.) and 5xx (server errors). Special categories are 0xx, those requests that fail before any significant processing can be accomplished, and 403, forbidden responses. The specified groups are monitored every sixty seconds and any increase beyond the specified threshold is reported. Groups and thresholds are provided to the qualifier using the following syntax. : An example would be 5:10 which would intrepreted as; for status group 5xx (500, 501, 502, etc.) any increase of ten or more over any one minute should be reported. The qualifier allows multiple values to be specified as in the following example /HTTP=(4:20,403:10,5:10) where a threshold of 20 is set for the 4xx group, 10 specifically for the 403 status (forbidden), and 10 for the 5xx group. SERVER GOING QUIET ------------------ The /QUIET qualifier allows a maximum expected period with no requests to be specified in seconds. (Somewhat obviously) if no requests are received for the period a report is issued. This period may be exceeded by up to /INTERVAL seconds. SPAWNED DCL REPORTING --------------------- The command provided by the /SPAWN qualifier may be anything the subprocess can execute. It would most commonly be the execution of a DCL procedure that would deliver the reporting in some site-specific manner. For example: /SPAWN=@PRODUCTION-DISK:[SUPPORT]WOTSUP_REPORT.COM The spawned command accesses the lines of the report for delivery via the multi-valued system-table logical name WASD_WOTSUP_REPORT. The following DCL commands provide an example of how to retrieve the values from such a logical. $ IDX = 0 $ REPORT_LOOP: $ LINE = F$TRNLNM ("WASD_WOTSUP_REPORT", "LNM$SYSTEM", IDX) $ IF LINE .EQS. "" THEN GOTO END_REPORT_LOOP $ WRITE SYS$OUTPUT LINE $ IDX = IDX + 1 $ GOTO REPORT_LOOP $ END_REPORT_LOOP: $!(all WOTSUP reports should contain at least four lines) $ IF IDX .LT. 4 THEN GOTO REPORT_LOGICAL_NAME_ERROR DETACHED PROCESS ---------------- The WOTSUP utility is intended to be run as a detached process. The DCL procedure WOTSUP.COM provides such an infrastructure. WOTSUP can also be run at the command line to provide some control over such a detached process. $ WOTSUP /DO=RESTART $ WOTSUP /DO=EXIT The first causes the WOTSUP image to exit and the WOTSUP.COM procedure to restart it. In this way a changed WASD_WOTSUP_PARAM logical name value can be reread by the utility changing it's run-time behaviour. The second causes the image to exit and the detached process to delete itself. USAGE EXAMPLES -------------- When the server is noticed to have exited, started or restarted, or the server process no longer exists (this set of events are always reported), and the first reporting to OPCOM CENTRAL and CLUSTER, the second to OPER1. $ WOTSUP /OPCOM $ WOTSUP /OPCOM=OPER1 Report server exit, startup, etc., any server process quota reaching 30% (the default) or less of maximum (the second example down to 15%), and reporting to OPCOM CLUSTER only as well as mailing a message to OPERATOR account. $ WOTSUP /QUOTA /OPCOM=CLUSTER /MAIL=OPERATOR $ WOTSUP /QUOTA=15 /OPCOM=CLUSTER /MAIL=OPERATOR These examples add HTTP status reporting, the first any one per minute 5xx (server error) status, the second an increase of ten per minute in the 5xx plus any 403 (forbidden) increase, and logging the reports to a site-specific file in addition to those destinations in the above examples. $ WOTSUP /QUOTA=15 /HTTP=5:1 /OPCOM=CLUSTER /MAIL=OPERATOR - /LOG=PRODUCTION_LOGS:WOTSUP_REPORTS.LOG $ WOTSUP /QUOTA=15 /HTTP=(5:10,403:1) /OPCOM=CLUSTER /MAIL=OPERATOR - /LOG=PRODUCTION_LOGS:WOTSUP_REPORTS.LOG This example expands the one above, adding a server quiet period of three minutes, reporting to two mail destinations (one via RFC822) and spawning a custom DCL command to report using a site-specific mechanism. $ WOTSUP /QUOTA=15 /HTTP=(5:10,403:1) /QUIET=180 /OPCOM=CLUSTER - /MAIL="OPERATOR,prod-mgr@home.net" - /LOG=PRODUCTION_LOGS:WOTSUP_REPORTS.LOG - /SPAWN=@PRODUCTION_DCL:WOTSUP_REPORTS.COM This final example reports to all of the specified destinations as a pre-production, or in-production change, integrity check of the reporting. $ WOTSUP /CHECK - /MAIL="OPERATOR,prod-mgr@home.net" - /LOG=PRODUCTION_LOGS:WOTSUP_REPORTS.LOG - /SPAWN=@PRODUCTION_DCL:WOTSUP_REPORTS.COM LOGICAL NAMES ------------- These are read each time they are required, and therefore can be modified without restarting the utility, in contrast to the command-line qualifiers that are only read at utility startup. If present they override anything supplied at the command-line. These are accessed using LNM$FILE_DEV and so can be defined in process, job or system tables (etc.) Using the system-level table allows the value to be modified without restarting the utility. WASD_WOTSUP_LOG same as /LOG qualifier WASD_WOTSUP_MAIL same as /MAIL qualifier WASD_WOTSUP_OPCOM same as /OPCOM qualifier WASD_WOTSUP_SPAWN same as /SPAWN qualifier The following logical name is used by non-interactive WOTSUP in place of any parameters supplied by the command-line. Defining this as a system-level logical allows the logical value to be modified and the utility restarted (obviating the need to modify WOTSUP wrapper procedures). WASD_WOTSUP_PARAM if present used instead of command-line parameters The following system-level logical names are created and used by the utility. WASD_WOTSUP_PID the PID of an executing, non-interactive WOTSUP WASD_WOTSUP_REPORT this is a multi-value logical created by WOTSUP in the SYSTEM table containing the lines of report text available to a spawned reporting DCL command QUALIFIERS ---------- /CHECK interactive check of /MAIL, /OPCOM and /SPAWN reporting /DBUG turns on all "if (Debug)" statements /DO= controls a detached process; DELETE, EXIT, RESTART /EXIT= seconds wait after exit without restart before alert /HTTP=: HTTP status group counter threshold (per minute) /HELP display brief usage information /INTERVAL= seconds between checking (default 15) /LOG[=] write alerts to this file as well /MAIL[=] one or more comma-separated email addresses (default is SYSTEM, can be RFC822 addresses) /OPCOM[=] target is CENTRAL, PRINTER, ... OPER12 (default is CENTRAL) /QUIET[=] maximum seconds without any request being processed (default is 300 - 5 minutes) /QUOTA= alert when a process quota gets below this percentage /SPAWN= when a report is required execute this command (there is a parameter as P1 containing a string) REQUIRED PRIVILEGES ------------------- WORLD for access to the server process' JPI data SYSPRV for access to the global section containing the server data to create logical names in the LNM$SYSTEM table BUILD DETAILS ------------- See BUILD_WOTSUP.COM COPYRIGHT --------- */ char CopyrightInfo [] = "Copyright (C) 2005 Mark G.Daniel\n\ This program, comes with ABSOLUTELY NO WARRANTY.\n\ This is free software, and you are welcome to redistribute it\n\ under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.\n"; /* VERSION HISTORY (update SOFTWAREVN as well!) --------------- 07-MAY-2005 MGD v1.0.0, initial development */ /*****************************************************************************/ #define SOFTWAREVN "v1.0.0" #define SOFTWARENM "WOTSUP" #ifdef __ALPHA # define SOFTWAREID SOFTWARENM " AXP-" SOFTWAREVN #endif #ifdef __ia64 # define SOFTWAREID SOFTWARENM " IA64-" SOFTWAREVN #endif #ifdef __VAX # define SOFTWAREID SOFTWARENM " VAX-" SOFTWAREVN #endif /* standard C header files */ #include #include #include #include #include /* VMS related header files */ #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include /* this header file contains the accounting structure definitions */ #include "../httpd/wasd.h" /* these are needed for (at least) VMS VAX V6.0 */ #ifdef __VAX # define SS$_FORCEX 11228 #endif /* __VAX */ /* these make it easier to have both VAX and Alpha declarations */ #define OPC$_RQ_RQST 3 #define OPC$M_OPR_CENTRAL 0x1 #define OPC$M_OPR_PRINTER 0x2 #define OPC$M_OPR_TAPES 0x4 #define OPC$M_OPR_DISKS 0x8 #define OPC$M_OPR_DEVICES 0x10 #define OPC$M_OPR_CARDS 0x20 #define OPC$M_OPR_NETWORK 0x40 #define OPC$M_OPR_CLUSTER 0x80 #define OPC$M_OPR_SECURITY 0x100 #define OPC$M_OPR_REPLY 0x200 #define OPC$M_OPR_SOFTWARE 0x400 #define OPC$M_OPR_LICENSE 0x800 #define OPC$M_OPR_USER1 0x1000 #define OPC$M_OPR_USER2 0x2000 #define OPC$M_OPR_USER3 0x4000 #define OPC$M_OPR_USER4 0x8000 #define OPC$M_OPR_USER5 0x10000 #define OPC$M_OPR_USER6 0x20000 #define OPC$M_OPR_USER7 0x40000 #define OPC$M_OPR_USER8 0x80000 #define OPC$M_OPR_USER9 0x100000 #define OPC$M_OPR_USER10 0x200000 #define OPC$M_OPR_USER11 0x400000 #define OPC$M_OPR_USER12 0x800000 #define BOOL int #define true 1 #define false 0 #define FI_LI "WOTSUP", __LINE__ #define VMSok(x) ((x) & STS$M_SUCCESS) #define VMSnok(x) !(((x) & STS$M_SUCCESS)) #define DEFAULT_INTERVAL_SECONDS 15 #define DEFAULT_EXIT_SECONDS 30 #define DEFAULT_QUIET_SECONDS 300 #define DEFAULT_QUOTA_MIN_PERCENT 30 #define SUSPENDED_RETRY_SECONDS 30 #define WASD_WOTSUP_LOG "WASD_WOTSUP_LOG" #define WASD_WOTSUP_MAIL "WASD_WOTSUP_MAIL" #define WASD_WOTSUP_OPCOM "WASD_WOTSUP_OPCOM" #define WASD_WOTSUP_SPAWN "WASD_WOTSUP_SPAWN" #define WASD_WOTSUP_PID "WASD_WOTSUP_PID" #define WASD_WOTSUP_REPORT "WASD_WOTSUP_REPORT" char ErrorSanityCheck [] = "sanity check", Utility [] = "WOTSUP"; long SysLckMask [2] = { PRV$M_SYSLCK, 0 }; BOOL DoCheck, Debug; int CliStatusCode403Delta, CliOpcomTarget, CliReportExitType, DefaultOpcomTarget = OPC$M_OPR_CENTRAL | OPC$M_OPR_CLUSTER, ExitStatus, InstanceGroupNumber = 1, /* default group number */ IntervalSeconds = DEFAULT_INTERVAL_SECONDS, JpiMode, JpiPid, LastExitStatus, PercentMinAst = DEFAULT_QUOTA_MIN_PERCENT, PercentMinBio = DEFAULT_QUOTA_MIN_PERCENT, PercentMinByt = DEFAULT_QUOTA_MIN_PERCENT, PercentMinDio = DEFAULT_QUOTA_MIN_PERCENT, PercentMinEnq = DEFAULT_QUOTA_MIN_PERCENT, PercentMinFil = DEFAULT_QUOTA_MIN_PERCENT, PercentMinPg = DEFAULT_QUOTA_MIN_PERCENT, PercentMinTq = DEFAULT_QUOTA_MIN_PERCENT, PreviousStartupCount, QuietSeconds, SecondsAfterExit; int CliStatusCodeDelta [1+5]; unsigned long SetPrvMask [2] = { PRV$M_SYSPRV | PRV$M_WORLD, 0 }; unsigned short