# soyMAIL

## Surprisingly Capable Web-mail for OpenVMS

### Installation and Administration

Published February 2024 for soyMAIL v2.1.0

Document generated using wasDOC 2.0.0

soyMAIL – Copyright © 2005-2024 Mark G. Daniel

###### Apache License, Version 2.0

###### License

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this software except in compliance with the License. You may obtain a copy of the License at

https://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.

Mark.Daniel@wasd.vsm.com.au
A pox on the houses of all spamers. Make that two poxes.

All trademarks within this document belong to their rightful owners.

The latest release of soyMAIL is available for download from

http://wasd.vsm.com.au/wasd/

Release notes for this version:

../release_notes.txt

# Table of Content

1.……………… | Introduction
2.……………… | Installation
2.1……………… | Authentication
2.2……………… | Apache (SWS)
2.3……………… | OSU
2.4……………… | WASD
2.5……………… | SMTP Relay
2.6……………… | HTML Editor
3.……………… | Configuration
3.1……………… | Directives
3.2……………… | [compose-charsets]
3.3……………… | [compose-user-from]
3.4……………… | [html-editor-load]
3.5……………… | [logout-realm]
3.6……………… | [private-access]
3.7……………… | [private-request]
3.8……………… | [public-access]
3.9……………… | [search-control]
3.10……………… | [smtp-default-host]
3.11……………… | [update-last-login]
3.12……………… | Conditional Configuration
3.13……………… | Regular Expression Overview
4.……………… | Autogenous Authentication
4.1……………… | Configuration
4.2……………… | Password Change
4.3……………… | Login Alias
4.4……………… | External Authentication Agent
4.5……………… | LOGIN.HTML
4.6……………… | CHANGE.HTML
4.7……………… | Access Log
5.……………… | Customization
5.1……………… | Locale
5.2……………… | Site
5.3……………… | User
6.……………… | soyMAIL User Files
7.……………… | Miscellaneous Topics
7.1……………… | Run-time Problem Solving
7.2……………… | Inconsistent State Data
7.3……………… | Site Contact / Mailing Lists
7.4……………… | General Access To Help
8.……………… | Index

# 1.Introduction

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

###### yahMAIL

soyMAIL is a native VMS application that executes as an HTTP server script providing authenticated Web access to an account's VMS Mail. All that is required at the client end is a (relatively) modern browser supporting CSS2/3. HTTP cookies are required for autogenous authentication.

soyMAIL has been built on experience gained hacking about with its progenitor yahMAIL but unlike yahMAIL was designed from the start to satisfy all the basic requirements for a Web-based email interface. It is the author's (perhaps) humble opinion that soyMAIL is a more than worthy successor as the 'son of yahMAIL'.

soyMAIL has been developed against these VMS Web server environments

- Apache (SWS) 2.2 and 1.3
- OSU 3.10
- WASD 12.n,11.n, 10.n, 9.n

for building and use on all VMS platforms

- Alpha
- Itanium
- x86-64
- (VAX is no longer supported)

and versions of VMS from V7.0 onwards.

soyMAIL supports

- receiving and sending
- native VMS Mail messages
- Internet (SMTP) mail messages
- MIME messaging and attachments
- HTML (rich) message text
- messages of non-Latin characters and directionality
  (for example Arabic, Cyrillic, Greek and Hebrew)
- message content search
- contact (address) maintenance
- VMS style mailing lists
- context-sensitive help
- user options (including supported language)

soyMAIL has a private access mode that allows authenticated access to an underlying VMS account's email facility. This is where it provides the 'classic' web-mail functionality. It also provides a public access mode which requires no authentication (though it is not forbidden either) and provides controlled access to a specific folder, in a specific mail file, in a specific VMS account, intended to allow general access to a managed subset of a users Mail.

soyMAIL has been carefully and extensively optimized to perform well within the general VMS environment and when using callable Mail.

It uses VMS callable mail to access an accounts mail repository and to perform native VMS messaging.

Messages are originated via SMTP by connecting directly to an SMTP server (usually but not necessarily on the localhost), and therefore requires access to an (at least local) SMTP relay, in much the same manner as many client-based email agents.

###### JavaScript required

soyMAIL was originally designed to have the essentials usable without having JavaScript available or enabled. Increasingly the functionality allowed using JavaScript has become more entrenched in both browsers and soyMAIL so that now while it may be still be possible to use soyMAIL without it the developer neither has that as an objective nor tests that any functionality works without it. Similarly, backward compatibility with browsers originally developed and tested against is not guaranteed. If you are not using a relatively up-to-date browser then you should be, if only from the security consideration.

# 2.Installation

2.1 Authentication
2.2 Apache (SWS)
2.3 OSU
2.4 WASD
2.5 SMTP Relay
2.6 HTML Editor

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

soyMAIL requires some configuration before use. It is recommended that this entire document be read and carefully considered before installation and attempted usage. Please use the facilities described in 7.1 Run-time Problem Solving when troubleshooting an installation.

soyMAIL soyMAIL is distributed as a source-code/run-time resource ZIP archive, with optional supplementary object code archives for each of the VMS platforms. For example, version two would be packaged

SOYMAIL200.ZIP SOYMAIL200-AXP.ZIP SOYMAIL200-IA64.ZIP SOYMAIL200-VAX.ZIP

It may be built from the primary archive using DECC 6 and later, or link-only using in addition one of the supplementary object code archives.

Brief installation and other relevant information can be obtained from the archive using the UNZIP option.

##### Link-only

A link-only build has the following alternate steps which can be used in any environment described below.

$ UNZIP device:[dir]SOYMAILnnn.ZIP $ UNZIP device:[dir]SOYMAILnnn-<arch>.ZIP $ @BUILD_SOYMAIL LINK

##### Update

An update (which does not overwrite the configuration file) has the following alternate step and can be performed in any of the environments described below.

$ @INSTALL UPDATE <server>

##### Run-time Components

The following table describes the run-time components. The installation procedure described below places these in the default locations the startup procedure expects to find them. Of course the default location and procedures are not mandatory. Components can be placed anywhere the site requires and a small, local startup procedure developed to use them from there.

Component | Purpose
--- | ---
[.OBJ_<arch>]SOYMAIL.EXE | architecture appropriate soyMAIL script executable, to [CGI-BIN], [BIN], etc. depending on the server
[.HELP] | help documentation, located via the logical name SOYMAIL_HELP
[.LANG] | language files located via the logical name SOYMAIL_LANG
[.THEME] | CSS and other thematic resource files located by the logical name SOYMAIL_THEME and by the script via the path /soymail/-/theme/
[.TINYMCE] | HTML (rich) text editor components
SOYMAIL.CSS | basic style-sheet for soyMAIL
SOYMAIL.CONF | configuration file located by the logical name SOYMAIL_CONFIG
SOYMAIL.JS | JavaScript used by soyMAIL
SOYMAIL_STARTUP.COM | startup procedure to define required logical names and install SOYMAIL.EXE image

The contents of the [.LANG], [.HELP], [.THEME] and [.TINYMCE] subdirectories in the soyMAIL distribution must be available to the server and script.

The INSTALL.COM procedure should provide a default run-time installation for each of the listed server environments.

## 2.1 Authentication

soyMAIL can be configured to depend on the supporting Web server to perform authentication and authorization using the standard HTTP challenge/response or to use it's own (autogenous) authentication and state management.

The configuration guidelines in following sections contain both file mapping and authorization configuration examples. The file mapping configuration is always required to allow the client browser to access thematic resources. The authorization rules should not be configured when using soyMAIL autogenous login and state management. See 4. Autogenous Authentication.

## 2.2 Apache (SWS)

This installation information is per SWS version 2.1. If you have a different version the requirements may require adjustment.

$ SET DEFAULT APACHE$ROOT:[000000] $ UNZIP <span style="font-style: normal">device:[dir]SOYMAILnnn.ZIP</span> $ SET DEFAULT [.SOYMAIL] $ @BUILD_SOYMAIL $ @INSTALL INSTALL APACHE
After installation files are located as follows.

File | Location
--- | ---
SOYMAIL.EXE | APACHE$COMMON:[CGI-BIN]
SOYMAIL_APACHE.COM | APACHE$COMMON:[CGI-BIN]SOYMAIL.COM
SOYMAIL_STARTUP.COM | APACHE$COMMON:[000000]
SOYMAIL.CONF | APACHE$COMMON:[CONF]

Apache requires the extra, script 'wrapper' procedure SOYMAIL.COM, so that the process-level logical name DECC$FILE_SHARING defined in the Apache scripting environment can be deassigned before the C-RTL is activated by the soyMAIL executable. This setting interferes with some soyMAIL file operations.

Mapping and authorization examples:

Alias /soymail/-/ "/apache$common/soymail/" <Location ~ ^/cgi-bin/soymail/~> AuthType Basic AuthName "OpenVMS authentication" AuthUserOpenVMS On require valid-user </Location>

Depending on the planned authorization source it may also be necessary to check that the OpenVMS authorization module is configured.

LoadModule auth_openvms_module modules/mod_auth_openvms.exe

Private access URI:

/cgi-bin/soymail/~

## 2.3 OSU

It is suggested to place the soyMAIL kit under WWW_ROOT:[000000].

$ SET DEFAULT WWW_ROOT:[000000] $ UNZIP device:[dir]SOYMAILnnn.ZIP $ SET DEFAULT [.SOYMAIL] $ @BUILD_SOYMAIL $ @INSTALL INSTALL OSU

After installation files are located as follows.

File | Location
--- | ---
SOYMAIL.EXE | WWW_ROOT:[BIN]
SOYMAIL_STARTUP.COM | WWW_ROOT:[SYSTEM]
SOYMAIL.CONF | WWW_ROOT:[CONF]

Mapping and authorization examples:

protect /htbin/soymail/~* www_system:soymail.prot pass /soymail/-/* /www_root/soymail/*

Private access URI:

/htbin/soymail/~

## 2.4 WASD

With WASD the soyMAIL kit occupies the usual location for source under the WASD_ROOT:[SRC] directory.

$ SET DEFAULT WASD_ROOT:[SRC] $ UNZIP device:[dir]SOYMAILnnn.ZIP $ SET DEFAULT [.SOYMAIL] $ @BUILD_SOYMAIL $ @INSTALL INSTALL WASD</pre>

File | Location
--- | ---
SOYMAIL.EXE | WASD_ROOT:[<arch-bin>-BIN]
SOYMAIL_STARTUP.COM | WASD_ROOT:[STARTUP]
SOYMAIL.CONF | WASD_ROOT:[LOCAL]

Mapping and authorization examples:

# WASD_CONFIG_MAP pass /soymail/-/* /wasd_root/src/soymail/* search=none set /**/soymail/~* map=once response=csp=* redirect /cgi-bin/soymail/~ /cgiplus-bin/soymail/~ # WASD_CONFIG_AUTH ["description"=REALM] /cgi-bin/soymail/~* r+w

Private access URI:

/cgi-bin/soymail/~

##### CGIplus

WASD provides the persistent scripting environment CGIplus. soyMAIL (1.6 and later) can execute in this environment. It remains resident and active for a period configured by the server. This can reduce response latency and system overhead significantly (request duration measurements indicate reductions of between 50% and 80% depending on activity). Just map soyMAIL into CGIplus space prior to other soyMAIL required rules.

# WASD_CONFIG_MAP redirect /cgi-bin/soymail* /cgiplus-bin/soymail*

##### Proctor

soyMAIL may be proctored (not sure what this means? — check section "Script Proctor" in "WASD Scripting Environment" document).

# WASD_CONFIG_GLOBAL [DclScriptProctor] 1 /cgiplus-bin/soymail /cgiplus-bin/soymail

## 2.5 SMTP Relay

soyMAIL originates SMTP Mail by directly communicating with a site's SMTP server. This requires that server to be enabled as an SMTP relay for at least the VMS system soyMAIL will be run on. The configuration for allowing relay varies on the TCP/IP and/or mail package in use (i.e. TCP/IP Services, MultiNet, TCPware, MX, PMDF, etc.)

##### CAUTION...

…must be exercised when changing configuration to allow relay.
The last thing that you need as a result is an open relay being used for spam propagation!

The following example shows a possible configuration for HP TCP/IP Services (a.k.a. UCX) to provide this for the local VMS system running the soyMAIL script. The configuration option to enable relaying must be set.

$ TCPIP TCPIP> SET CONFIGURATION SMTP/OPTION=RELAY ^Z

And an entry placed in the plain-text configuration to enable access for allowed SMTP clients (the localhost).

# TCPIP$SMTP_COMMON:SMTP.CONFIG Good-Clients: 127.0.0.0,localhost

The SMTP server that the soyMAIL script connects to is commonly running on the same (VMS) system as the script. It does not need to be. The configuration directive [SMTP-server-host] (see 3.1 Directives) can be used to specify and alternate host name or IP address (and non-default port if required) for soyMAIL to connect to.

## 2.6 HTML Editor

TinyMCE is supplied as an integrated element of soyMAIL. Although soyMAIL itself has no specific requirement for installation on an ODS-5 volume, TinyMCE has file names containing multiple periods. UNZIPing the soyMAIL archive on an ODS-2 volume will generally result in UNZIP converting non-ODS-2 syntax elements into something legal for the file-system. Illegal periods are substituted with underscores. Of course TinyMCE will still be expecting multiple periods so the soyMAIL script is given these to munge into underscores on behalf of the file-system (well it's given all resource file requests but only munges those necessary). This does introduce some additional latency for non-ODS-5 environments. The capability requires some mapping rules.

These are the WASD example (modify to suit your web server):

# WASD_CONFIG_MAP # anything with the usual resource path is given to the script to munge redirect /soymail/-/* /cgiplus-bin/soymail/soymail/_/* # the alternate resource path containing ODS-2 legal names is then used pass /soymail/_/* /wasd_root/src/soymail/*

# 3.Configuration

3.1 Directives
3.2[compose-charsets]
3.3[compose-user-from]
3.4[html-editor-load]
3.5[logout-realm]
3.6[private-access]
3.7[private-request]
3.8[public-access]
3.9[search-control]
3.10[smtp-default-host]
3.11[update-last-login]
3.12 Conditional Configuration
3.13 Regular Expression Overview

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

soyMAIL configuration is provided using a plain-text file located using the logical name SOYMAIL_CONFIG. The configuration file must exist or all access is denied. The installation procedure copies an example configuration file allowing private access and requiring some customization. Updates do not subsequently change this file. Comments may be included by prefixing the line with a '#' character. Each directive name is delimited by '[' and ']' characters and directive parameters comprise all text until the next comment or directive opening '['. Reserved characters may be escaped using the backslash character. Leading and trailing white-space is trimmed. Comments and directives must begin in column 1.

Tpical configuration file might look something like

######################## # private soyMAIL access ######################## [if-private] [private-access] */*/* [page-title] The Company Name [page-title2] IT Services [message-list-footer] <center>~ IT Services can be contacted on 82596189 ~</center> [print-header] The Company Name [print-footer] ~ Internet, E-mail and Web Services ~ [help-about-site] <b><a href="http://the.host.name/">The Company Name</a></b> provides OpenVMS consultancy, programming and support, along with Web and Mail hosting. [end]

Comments, directive names and directive data can be seen.

## 3.1 Directives

The following table provides a summary of all directives, with those requiring more explanation expanded in following sections.

Directive | Description
--- | ---
[access-log] | generates a soyMAIL-specific access log file when autogenous authentication is in use (see 4.7 Access Log)
[attachment-mime-types] | comma-separated MIME types a browser will display in-window. Others will always be opened in a separate window.
[charset-default] | character set to use for folder listing, options and contacts
[compose-charsets] | comma-separated list of character sets available on the message composition page (see 3.2 [compose-charsets])
[compose-contacts-after] | expand the contacts list viewport after this many entries
[compose-contacts-size] | expand to this number of lines (em)
[compose-edit-cols] | comma-separated integers providing the steps the message edit window columns increment; e.g. 78,96,132
[compose-edit-rows] | comma-separated integers providing the steps the message edit window rows increment; e.g. 20,30,40
[compose-user-from] | When ENABLED allows the user to specify the message "From:" header line. When DISPLAY just displays it on the page.
[compose-wrap-at] | comma-separated integers providing the steps after which the message text should be wrapped; e.g. 78,96,132
[context-cache-expires] | With WASD CGIplus VMS Mail contexts are maintained in the persistent script for this number of minutes (default 60)
[disk-quota-percent] | With each folder opened soyMAIL checks the users consumed disk quota. When it exceeds this percentage it adds a notification to the status information. Defaults to 85 percent. To disable completely set above 100. To display permanently set to 0.
[downtime] | string disables the use of soyMAIL and gives the specified string as a simple announcement to users connecting to soyMAIL
[font-family-local] | Additional font families presented in the user options font selector. One per line.
[greeting] | Message presented in the status panel when a client first accesses soyMAIL, or its help or about pages. Can be used as a welcome or warning message.
[help-about-site] | site-specific information presented on the Help 'About' page
[html-editor-load] | Include and process the specified configuration file at the point of inclusion. Included files may be nested up to three deep. Just remember, each configuration file is one that must be read from the file-system for each soyMAIL request!
[login-acme-doi] | ACME domain of interpretation (see section 4. Autogenous Authentication)
[login-acme-no-restrict] | ignore any login source restriction (e.g. /NONETWORK) provided authentication was successful (see section 4. Autogenous Authentication)
[login-agent] | external, site-provided authentication agent (see 4. Autogenous Authentication)
[login-alias] | mapping from user-supplied user-name string to username used for autogenous authentication (see 4. Autogenous Authentication)
[login-alias-smtp-from] | when ENABLED and building a compose self address ("From:") use any mapped alias as the local part
[login-autocomplete] | browser auto-completion of login credentials (see 4. Autogenous Authentication)
[login-change-page] | file-system location for password change page (see 4. Autogenous Authentication)
[login-idle] | seconds idle before credential reentry (see 4. Autogenous Authentication)
[login-language] | language for login page (see 4. Autogenous Authentication)
[login-no-pwdexp] | ignore expired passwords (see section 4. Autogenous Authentication)
[login-page] | file-system location for login page (see section 4. Autogenous Authentication)
[login-secret] | encryption key for credential cookie (see 4. Autogenous Authentication)
[login-type] | integer representing NETWORK, LOCAL, REMOTE, etc. (see 4. Autogenous Authentication)
[login-verify] | seconds between credential verification (see 4. Autogenous Authentication)
[logout-realm] | enables the logout button and functionality (see 3.4 [html-editor-load]).
[message-list-footer] | site-specific information (HTML text) presented in a separate panel below the folder message listing
[page-title] | Superior line in main menu panel. Titles all pages.
[page-title3] | the text in [page-title] is forced left and the [page-title2] text is forced right
[print-header] | text header for printed mail messages
[print-footer] | text footer for printed mail messages
[private-access] | allows mapping between authenticated user (CGI remote-user) and a VMS username (see 3.6 [private-access])
[private-request] | indicates this request is for private access (see 3.7 [private-request])
[public-access] | permits and maps request path strings to VMS Mail user names, mail file and folders (see 3.8 [public-access])
[public-footer] | site-specific information (HTML text) presented in a separate panel below the public message listing ("Thanks to ...")
[public-request] | Indicates this request is for public access. Complements the [private-request] directive.
[search-control] | controls designed to limit the impact of intensive searching activity on system resources (see 3.9 [search-control])
[site-style-sheet] | loads the URL-specified style after the theme (and can therefore also be used to supplement or override a theme style)
[smtp-default-host] | specifies a host or domain name and makes an unqualified user address such as Mark.Daniel into an RFC (Internet-style) address such as Mark.Daniel@vsm.com.au (see 3.10 [smtp-default-host])
[smtp-from-host] | used when constructing the 'user@from.host.name'
[smtp-server-host] | Host name/address of SMTP server soyMAIL connects to for Internet mail transport (defaults to 'localhost'). A non-default port may be specified using host:port (e.g. 'localhost.:2525')
[soymail-at-title] | site description provided in title bar of browser window (defaults to "soyMAIL @ the.server.name")
[update-last-login] | update SYSUAF last-login with each initial access (see 3.1 Directives)
[user-name-info] | When ENABLED display on the status panel the logged-in user name. When ALIAS (and [login-alias] in use) displays the login alias.
[user-options-default] | allows the soyMAIL administrator to preset some options (e.g. language) by providing options configuration text against this directive (it is required to escape each leading '[' with a '')
[user-options-override | allows the soyMAIL administrator to override user selected options by providing options configuration text against this directive (it is required to escape each leading '[' with a '')
[vms-occluded] | 'hides' obvious VMS-specific aspects of soyMAIL (e.g. VMS options panel, the extract button on the message read page)

## 3.2[compose-charsets]

By default soyMAIL message composition is performed using the character set specified by the user-optioned language ([lang_charset] in the language file, commonly ISO-8859-1). The [compose-charsets] directive allows composition of a message in another character set and can be enabled in the user option file (for a per-user configuration) or the soyMAIL configuration file (for site-wide availability). Each item is then displayed in a selection list on the message composition page.

The format for each item of the directive is

description = [<] charset-name
where the description is displayed in the list, the optional '<' flag indicates the script directionality is right-to-left (as with Arabic and Hebrew) and the charset name is the MIME (IANA) standard name for the character set.

The following example provides a selection of Arabic, Greek and Hebrew.

[compose-charsets] Arabic=<ISO-8859-6,Greek=ISO-8859-7,Hebrew=<ISO-8459-8

An equivalent field is available in the user options.

During message composition the desired character set must be selected by the user before entering any message text.

## 3.3[compose-user-from]

When this directive is ENABLED the message composition page provides an additional "From:" text entry field (immediately above the"To:" field) allowing the user to easily change the message origination (From:) address. Of course while there are legitimate uses for this facility it does provide potential for a certain no-brain email spoofing. If DISPLAY then the same field is provided for informational purposes but cannot be modified.

When ENABLED it also allows one or both of two additional directives to be prepended to a user signature. When the signature is appended to a message these directives set the From: and/or Reply-to: fields of the message. This facility allows various email "personas" to be maintained simply and associated with messages as required.

An example showing the specification of both:

[SMTP-from] Mark.Daniel@another.host.entirely [SMTP-reply-to] Mark.Daniel@wasd.vsm.com.au -- This is the signature part. Mark Daniel

Note that there already exists the user option [SMTP-from] that allows specification of prefered From: field. To administratively disable this facility completely override the user option with a configuration specifying an exclamation point, such as:

[smtp-from] !

## 3.4[html-editor-load]

soyMAIL supports plug-in JavaScript HTML editors for HTML message composition.

TinyMCE is provided as part of the soyMAIL package. This is enabled by having an asterisk as this directive's parameter; disabled by having the parameter empty.

Another editor may be used if desired. The functions htmlEditorContent() and htmlEditorLoad() must be present, being an onload=target for the document. If the parameter contains a script> keyword the JavaScript overrides the default TinyMCE initialisation.

The following is an example:

[html-editor-load] <script type="text/javascript" src="/tinymce/jscripts/tiny_mce/tiny_mce.js"> </script> <script type="text/javascript"> tinyMCE.init({ mode : "exact", elements : "compose_text", theme : "advanced", plugins: "preview,print,insertdatetime", theme_advanced_buttons1_add: "fontselect,fontsizeselect", theme_advanced_buttons2_add: "preview,print", theme_advanced_buttons3_add: "insertdate,inserttime", theme_advanced_buttons3_add_before: "forecolor,backcolor" }); function htmlEditorContent() { return tinyMCE.getInstanceById("compose_text").getContent(); } function htmlEditorLoad() { /* nothing required for TinyMCE! */ }

## 3.5[logout-realm]

This configuration directive only applies when using Web server authorization. It is not needed and is not used when using soyMAIL own authentication and state management (see 4. Autogenous Authentication). The following description only applies to Web server HTTP authorization.

The soyMAIL [logout] button and functionality is based on a Kludge that tries to hoodwink the browser into thinking its cached credentials are no longer valid. It does this by returning an HTTP 401 response (authentication required) itself as a response to hitting the [logout] button. The idea is to present to the browser a refusal to use the supplied username/password against the request path whereupon the browser purges the entry from its credential cache.

As described above this is a Kludge with a capital K. Why HTTP/1.1 didn't include a 418 (authorization canceled) cancelled or some mechanism such as this or know! Not only are there inconsistencies in the way browsers handle this (hence the credential clear, [ok] and final [cancel]) there are some issues in getting a CGI application issued Status: 401 authorization required through the server sufficiently unscathed and functional as to be recognised by the browser as an authorization refusal. So...

WASD handles all this with its usual panache :-)

VMS Apache and OSU need some additional working-around. Hence the [logout-realm] directive. Unless this is set the [logout] button is greyed-out (italicised) and the functionality disabled. This must be set to exactly the same string used by the authorization realm configured against the soyMAIL path in the servers configuration. If it not exactly the same string some servers go into infinite loops, some browsers re-request ad-infinitum, etc. You have been warned!

For an Apache configuration of:

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

the soyMAIL configuration would be set

[logout-realm] VMS account

The soyMAIL configuration directive may also be set to a single hyphen to disable the logout button and functionality.

## 3.6[private-access]

Private-access is a term used to describe a client making authenticated access to an underlying VMS accounts email facility.

The private access URI must have been made subject to either Web server authorization, or to soyMAIL autogenous authentication (section 4. Autogenous Authentication). If there is no browser username/password dialog, or no login page, then it's not configured correctly!

soyMAIL identifies private access when the path has the leading characters /~. For example, in the case of Apache and WASD

/cgi-bin/soymail/~

Alternatively, a site-specific private sentinal can be configured using the [private-request] configuration directive (see 3.7 [private-request]).

There needs to be a explicit configuration directive to enable private access and optionally to map between authenticated users and VMS usernames. The general format is

<remote-user>/<realm>/<vms-username>

The realm allows WASD authentication realms to be factored into the mappings but almost always will remain an asterisk.</p> <p class="western">If there is a one-to-one correspondence between the Web-server authenticated user name (as it is common to use some form of SYSUAF-based authentication this is usually the case) then a simple rule against the directive is enough to allow any user access to Mail.

*/*/*

Specific accounts can be denied access by deliberately disrupting the mapping. In this case the SYSTEM and ANOTHER accounts are mapped to non-existing accounts _SYSTEM and _ANOTHER.

[private-access] system/*/_system another/*/_another */*/*

Using the same mechanism a non-VMS-account remote user may be mapped into the mail of an existing VMS username.

[private-access] freddo/*/nurkf jd/*/doej */*/*

##### Postmaster

POSTMASTER is a flag that can be placed against any user name. It allows a username to be specified in the soyMAIL path different to that of the authenticated username (normally this will result in a soyMAIL "insufficient privilege or object protection violatiotion" fatal error). For example

/cgi-bin/soymail/~daniel/

This postmaster can then do anything using soyMAIL the specified username can do. Such an account is flagged in the following manner.

[private-access] whomever/*/(POSTMASTER) */*/*

Note that POSTMASTER here is not an account. It is a soyMAIL characteristic flagged against the username. The parentheses are required.

## 3.7[private-request]

By default the leading characters /~ of the path indicates to soyMAIL a private access request. This directive overrides that tilde sentinel and allows any request to be recognized for private access. It intended to be used inside a conditional configuration test (see 3.12 Conditional Configuration) based on some characteristic of the request reflected in a CGI variable.

The following example shows a configuration test for the presence of a REMOTE_USER variable indicating it is a request subject to server authorization.

[if-CGI-remote_user] [private-request] [end-if]

This effectively directs soyMAIL to consider any such authorized request is private access.

The second example shows a test based on the request script name and assumes that the server has mapped the path /mail onto the soyMAIL executable.

[if-CGI-script_name] ^^/mail$ [private-request] [end-if]

The first leading caret indicates it is a regex pattern; the second a regex 'beginning of line' symbol; then the string used to activate soyMAIL; and a regex 'end of line' dollar symbol. This makes it an exact match test.

Note that the [private-request] directive must be specified before the use of any directives </font></samp>that rely on recognition of private or public access (e.g. [if-private], [if-public], [private-access], [public-access], etc).

## 3.8[public-access]

This facility is intended to allow general access to a managed subset of a users Mail. Public access requires no authentication (though it is not forbidden either). There are three variations on public access. The first rigidly controls access to a specific folder, in a specific mail file, in a specific VMS account. The second, a wildcard folder specification, allows access to any folder in the specified mail file and account. The third, also a wildcard specification, prohibits access to the account MAIL and NEWMAIL folders.

The general format is

/<public-path>/ /<username>/<mail-file>/<folder-name>/
with the full wildcard variant
/<public-path>/ /<username>/<mail-file>/*/
and the prohibited MAIL and NEWMAIL wildcard variant
/<public-path>/ /<username>/<mail-file>/*!/

Both wildcard variants allow an initial folder to be specified

/<public-path>/ /<username>/<mail-file>/*<folder>/<br/> /<public-path>/ /<username>/<mail-file>/*!<folder>/

The public path string is used in the URL and need not be related to any part of the real components of the mail access.

[public-access] /an_example/ /NURKF/MAIL/PUBLIC/ /another_example/ /DOEJ/ARCHIVE/MAIL/ /public/ /LARRY/MAIL/*!MY_PUBLIC/

The first rule would map the URL

http://the.host.name/cgi-bin/soymail/an_example/
to VMS account NURKF, the default mail file MAIL.MAI and the PUBLIC folder in that. The second rule maps the URL
http://the.host.name/cgi-bin/soymail/another_example/
to the JOED account, mail file ARCHIVE.MAI and folder MAIL in it.

The third rule maps the URL

http://the.host.name/cgi-bin/soymail/public/
to the LARRY account, mail file MAIL.MAI and an initial folder MY_PUBLIC, with access allowed to all other folders except MAIL and NEWMAIL.

## 3.9[search-control]

Mail message searching can be a very compute and I/O intensive activity. Essentially soyMAIL searching is performed on two levels with significantly different expenses.

- Message header content. From, to, cc, subject and date parameters are all available via callable Mail without needing to access the message body. This makes searching on these very inexpensive.
- Message body content. This requires not only reading the body of the message but also commonly decoding the MIME content of messages and can be quite expensive. In addition performing a textual search of the body of a message is obviously a source of intense CPU activity.

Regular expression matching is significantly more CPU intensive than keyword matching.

The following parameters to the [search-control] directive allow fine control of the extent of search capability to assist in managing the system impact of this activity. Conditional configuration (see below) makes it possible to apply these to some requests and not others. One or more, space-separated, can be used against the directive.

Parameter | Description
--- | ---
full | Is the default if [search-control] is not configured.
header-only | As described above this is quite lightweight.
keyword-only | Disable regular expression matching. It is still available to configuration directives.
priority=<integer> | Once message body searching begins this moves the script process priority to that specified (0..4) and restores it when searching completes.
none | Disables searching completely (and is obviously the least expensive :-)

## 3.10[smtp-default-host]

This directive allows a host/domain name to be automatically appended to an unqualified user name (i.e. an address with a local but no @domain part). With this set to the.host.name entering an address of Mark.Daniel would result in a send to Mark.Daniel@the.host.name.

soyMAIL adds the default host/domain part before sending or whenever the page is refreshed. The modification to the address can be requested at anytime by selecting the [compose] button and thereby refreshing the page.

Setting this directive disables a default send via VMS Mail. VMS Mail can still be used by prepending a node name to the address (e.g. '0::DANIEL', 'DELTA::DANIEL', etc.)

## 3.11[update-last-login]

For sites with a requirement to track continued account usage this directive results in the SYSUAF interactive or non-interactive (default) last-login datum being updated with each initial access. An initial access is defined as a startup GET request from entering the private access URL into the browser or selection of a bookmark/favourite. Continued use of an established session (using the buttons or new mail check facility) does not result in updates to the last-login date/time.

Parameter to this directive should be INTERACTIVE or NON-INTERACTIVE.

## 3.12 Conditional Configuration

soyMAIL has a useful facility allowing dynamic configuration of soyMAIL processing based on request characteristics and CGI variable content. This allows a single configuration file to support multiple site appearances or capabilities.

Conditional directives begin with a test. Some are booleans. For CGI tests it either looks for the keyword provided with the test directive in the specified CGI variable value, or uses it as a regular expression (regex) to match against the variable value (EGREP compliant). A regular expression must be prefixed by a caret character ('^') which of course is not used as part of the expression. If a CGI variable doesn't exist it is treated as an empty string.

Directive | Description
--- | ---
[if-CGI-<name>] | If the CGI variable specified by <name> matches the directive string then process the directives to the corresponding [if-end].
[if-not-CGI-<name>] | If the CGI variable specified by <name> does not match the directive string then process the directives to the corresponding [if-end].
[if-private] | If soyMAIL is being used to access private mail.
[if-public] | If being used to access public mail.
[if-end] | Terminates a block started by a matching [if-..] directive.
[end] | WARNING: Terminates all further configuration processing at that point. This is intended merely to save a few CPU cycles. Deploy inside relevant [if-..] directives.

##### Keyword Example

[if-CGI-http_host] the.host.name [if-CGI-server_name] the.server.name [if-not-CGI-remote_user] R_J_ECUREUIL

##### Equivalent Regex Example

[if-CGI-http_host] ^.*the.host.name.* [if-CGI-server_name] ^.*the.server.name.* [if-not-CGI-remote_user] ^.*R_J_ECUREUIL.*

##### Regex Equivalents of Common Wildcards

asterisk ('*') | matches zero or more characters | period then asterisk ('.*')
question mark ('?') | matches any single character | period ('.')
Percentage ('%') | matches any single character | period ('.')

##### Tests

Empty and non-empty strings may be tested for using an empty parameter to the directive.

If the variable contains a value then the following test will be true. If the variable does not exist or has an empty value then it will be false.

[if-CGI-variable_name>]

If the variable does not exist or contains an empty value then this second test will be true. If it contains a value then it will be false.

[if-not-CGI-variable_name>]

##### Conditional Configuration Example

# first directives for private access [if-private] [page-title] The Page Title [if-CGI-server_name] www.site1.com [message-list-footer] For more information on Site 1 see ... [if-end] [if-CGI-server_name] www.site2.com [message-list-footer] For more information on Site 2 see ... [if-end] [if-end] # # then directives for public access [if-public] [page-title] The Public Page [message-list-footer] Just an public example! [public-access] /public-2005/ /WEBMASTER/MAIL/PUB2005/ [if-end]

## 3.13 Regular Expression Overview

soyMAIL employs the GNU RX1.5 regular expression package. Evaluation is done using case-insensitive, EGREP-compatible matching. A detailed tutorial on regular expression capabilities and usage is well beyond the scope of this document. This summary is only to serve as a quick mnemonic. Also see

https://en.wikipedia.org/wiki/regular_expression

Description | Usage
--- | ---
Match-self Operator | Ordinary characters
Match-any-character Operator | (period)
Concatenation Operator | Juxtaposition
Repetition Operators | + ? {}
Alternation Operator | |
List Operators | [...] [^...]
Grouping Operators | ..)
Back-reference Operator | digit
Anchoring Operators | $
Backslash Operator | Escape meta-character e.g. \ ^ . $ | [ (

The following operators are used to match one, or in conjunction with the repetition operators more, characters of the target string. These single and leading characters are reserved meta-characters and must be escaped using a leading backslash ("\") if required as a literal character in the matching pattern.

Expression | Purpose
--- | ---
^ | Match the beginning of the line
. | Match any character
$ | Match the end of the line
| | Alternation (or)
[abc] | Match only a, b or c
[^abc] | Match anything except a, b and c
[a-z0-9] | Match any character in the range a to z or 0 to 9

Repetition operators control the extent, or number, of whatever the matching operators match. These are also reserved meta-characters and must be escaped using a leading backslash if required as a literal character.

Expression | Purpose
--- | ---
* | Match 0 or more times
+ | Match 0 or more times
? | Match 1 or 0 times
{n} | Match exactly n times
{n,} | Match at least n times
{n,m} | Match at least n but not more than m times

##### Checking Regular Expressions

soyMAIL can be used at the command line to check the results of regular expression pattern matching. This can assist with creating conditional configuration. Assign soyMAIL as a foreign verb and use as illustrated.

$ SOYMAIL /REGEX <text to be matched> <pattern>

# 4.Autogenous Authentication

4.1 Configuration
4.2 Password Change
4.3 Login Alias
4.4 External Authentication Agent
4.5 LOGIN.HTML
4.6 CHANGE.HTML
4.7 Access Log

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

Access to private Mail via soyMAIL always requires user authentication. This may be performed as HTTP authorization by the supporting Web server (and passed as CGI variable REMOTE_USER), or by having soyMAIL maintain it's own authentication state. This section describes the latter.

The main advantage in allowing soyMAIL to manage it's own authentication environment is a clearly defined login-usage-logout life-cycle, something at best a kludge with HTTP authorization. It provides a one-click [logout] button that really works!

The client browser must support and have enabled HTTP cookie functionality. A cookie is used to store and propagate the authentication state. The cookie expires at the close of the browser. The cookie value is encrypted using the industry standard RC4 algorithm. This data is only present as plain values inside the processing of soyMAIL.

soyMAIL authentication

- accepts the VMS username and password via it's own login page
- verifies those credentials
- maintains verified credentials for the duration of the session
- session is terminated by using the [logout] button, or fully closing the browser

In addition soyMAIL

- continues to verify the credentials periodically
- will request the credentials be reentered after an idle period

The internal authentication mechanism (site-specific, external authentication is possible, see 4.4 External Authentication Agent) depends on the VMS platform and version.

- For Alpha and Itanium with VMS V7.3 or later it uses the ACME authenticator and $ACM system services. This is a vendor maintained service and so may be considered as-good-as bullet-proof. It supports everything ACME supports including DOI, external authentication, intrusion management, etc.
- For VAX and VMS versions earlier than V7.3 it uses a combination of $SCAN_INTRUSION, $GETUAI and $HASH_PASSWORD to parallel most of the relevant functionality provided by ACME. These include intrusion management and account login constraints. It's potentially not as bullet-proof as the vendor solution and should be used advisedly.

Further discussion will be confined to ACME authentication.

With autogenous authentication any account that can normally login to the supporting VMS system can access soyMAIL. To restrict an account it is necessary to deny access using the [private-access] directive (section 3.6 [private-access]).

Technical detail on the encryption algorithm, authentication code, cookie structure, etc., can be obtained from the descriptive prologue of the LOGIN.C source code module.

## 4.1 Configuration

If Web server authorization for soyMAIL is currently configured then disable this before proceeding further. Behaviour with both enabled is indeterminate.

Autogenous authorization is enabled by configuring a value against the soyMAIL configuration directive [login-secret]. This is used as a key to encrypt the soyMAIL credential cookie value. When this directive has a value against it soyMAIL attempts to establish it's own authentication state. As this is an encryption key care should be taken to ensure it is

- as long as practicable (soyMAIL insists on a minimum of 24 characters)
- comprises a 'random' mix of mixed-case alphanumeric and punctuation characters
- kept secure (SOYMAIL.CONF is not world-accessible, etc.)

An example configuration might be

[login-secret] aic84+-[QsfOPa,dk;'12ndjve64_90mhd43m*2$

## 4.2 Password Change

soyMAIL authentication will detect an expired password for DIALUP, LOCAL and REMOTE login types. ACME does report expiration for NETWORK (the default). An expired password will fail unless [login-no-pwdexp] is ENABLED or soyMAIL password change is configured and the password must be changed at login.

Password change is enabled by specifying the location of the change dialog HTML (also see 4.6 CHANGE.HTML). Using the default file that would be

[login-change-page] SOYMAIL_THEME:CHANGE.HTML

As with authentication password change is either performed by ACME or a soyMAIL code path. The latter is rudimentary and does not include such desirable facets as dictionary and password history checking. Platforms without ACME available should avoid enabling password change.

The following configuration directives will modify the login type from the default NETWORK. Choose a type in-line with site policy.

[login-type] 3 | LOCAL
[login-type] 4 | DIALUP
[login-type] 5 | REMOTE

## 4.3 Login Alias

For autogenous authentication the configuration directive [login-alias] allows the supplied user name string to be mapped to another string before being used for authentication. For example, this might allow the user email address, or local mailbox name, to be used as the user name and mapped to an actual VMS username before authenticating against the SYSUAF. In fact any arbitrary string can be mapped to any other. The alias mapping is performed using a case-insensitive match.

The format is one alias mapping per line, with the supplied user name to be matched on the left, a forward-slash, and the username to be authenticated against on the right.

[login-alias] Mark.Daniel/DANIEL Fred.Bloggs/BLOGGS

If a match is not made and no mapping has occurred the default (drop-through) behaviour is to use the original supplied user name string and so in the above configuration both "Mark.Daniel" and "DANIEL" would authenticate against the DANIEL account, "Fred.Bloggs" and "BLOGGS" against BLOGGS. Of course any other supplied user name could also authenticate directly. To prevent any other than an aliased user name being used for authentication conclude the list with "*/-".

[login-alias] Mark.Daniel/DANIEL Fred.Bloggs/BLOGGS */-

In the above example only "Mark.Daniel" and "Freg.Bloggs" can be authenticated.

The (somewhat redundant) mapping "*/*" will terminate alias processing and explicitly direct authentication to occur using the supplied user name (the default drop-through behaviour anyway).

The configuration directive [login-alias-smtp-from] when ENABLED uses any such mapped alias as the local part of a compose page self address ("From:") In this way an alias such as "Mark.Daniel" would be used to build an address Mark.Daniel@the.host.name

## 4.4 External Authentication Agent

This provides a site-specific, external-to-soyMAIL authentication mechanism. If the [login-agent] configuration directive exists then it activates an external authentication DCL procedure within a subprocess. The DCL procedure must be specified following an '@' symbol and must have execute permission for the scripting account. For example

[login-agent] @cgi-bin:[000000]soymail_authage.com

Optional parameters can be provided as part of the configuration directive:

[login-agent] @cgi-bin:[000000]soymail_authage.com "param1" "PARAM2"

When activated the procedure has a further three parameters appended to any supplied in the above configuration directive; "<username>", "<password>" and "<remote_addr>", to be used in the authentication processing.

The procedure should exit with any success status (e.g. SS$_NORMAL) to indicate successful authentication or any error status (e.g. SS$_NOPRIV) to indicate authentication failure.

This is a (very simple) example.

$ SET ON $ OK = 1 $ NOPRIV = 36 $ P1 = F$EDIT(P1,"UPCASE") $ IF P1 .EQS. "CURLY" .AND. P2 .EQS. "JeromE" THEN EXIT OK $ IF P1 .EQS. "LARRY" .AND. P2 .EQS. "lOUIs" THEN EXIT OK $ IF P1 .EQS. "MOE" .AND. P2 .EQS. "harrY" THEN EXIT OK $ EXIT NOPRIV

This would probably be more like a working one.

$ SET ON $ SOYAUTH = "$location:SOYAUTH.EXE" $ SOYAUTH "''P1'" "''P2'" "''P3'" $ EXIT $STATUS

## 4.5 LOGIN.HTML

The HTML used in the login page is derived from a file. The default is [.THEME]LOGIN.HTML and contains a functional login form and layout. This can be customized to include a site theme, logo, information, etc. Care must be taken not to disturb any of the core functionality of the HTML form, form fields, etc.

So that subsequent updates to not overwrite modifications to the base LOGIN.HTML It is suggested to copy this to something like _LOGIN.HTML and then set that as the login page via soyMAIL configuration.

[login-page] SOYMAIL_THEME:_LOGIN.HTML

## 4.6 CHANGE.HTML

The HTML used by the password change page (see 4.2 Password Change) is also derived from a file. The default is [.THEME]CHANGE.HTML and contains the required elements to support the change dialog. Like the login page it can receive some customisation where care is taken not to disturb its core functionality.

As with the login page it is suggested a copy be modified and configured.

## 4.7 Access Log

When autogenous authentication is in use the Web server does not perform the authorization function itself and as a result the 'remote user' datum, usually included in server-access logs, is not available. Which accounts are using soyMAIL is often useful or mandatory audit information and so soyMAIL provides this as a supplemental access log file.

A configuration directive enables the facility and allows a file specification to locate the log.

[access-log] WASD_LOGS:SOYMAIL.LOG

To assist in the maintenance of such logs soyMAIL will rotate the file name based on time using (perhaps familiar) formatting directives included in the configuration directive. For example, to include the year in a soyMAIL access log file name use

[access-log] WASD_LOGS:SOYMAIL_%04d.LOG

In a similar fashion, to include the month add a second numeric formatting string, and the day-of-month a third, as illustrated in the following two examples.

[access-log] WASD_LOGS:SOYMAIL_%04d%02d.LOG [access-log] WASD_LOGS:SOYMAIL_%04d%02d%02d.LOG

soyMAIL enables SYSPRV to access the file and so it may be located in a protected area of the file-system.

This file is provided in the NCSA-style 'combined' format only to allow processing by common access log file tools if desired. All fields are present and valid except the 'bytes' datum which always contains zero. Of course this log is only intended to supplement the server log, not supplant it.

# 5.Customization

5.1 Locale
5.2 Site
5.3 User

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

soyMAIL provides three levels of customization.

- locale
- site
- user

## 5.1 Locale

The [.LANG] directory contains the default English language message file, EN.TXT. This can be copied to another, language-indicative file name and the text of the messages modified appropriately. The content of these files is not intended to be used for site-local changes to messages. Directives in the soyMAIL configuration file are for this purpose. The language files are global components of the soyMAIL distribution.

If you wish to put a language-specific message file together for soyMAIL please contribute it back into the soyMAIL community. Note that messages can be used in all sorts of contexts, particularly inside string literal quotes - both single and double. It is therefore necessary to substitute the HTML entities &quot;, &rsquo;, etc., for anything that might be misinterpreted as JavaScript code quotes (i.e. " (0x22) and ' (0x27)). If soyMAIL reports a message file fatal error the SOYMAIL$WATCH facility (see 7.1 Run-time Problem Solving) can be used to help determine the underlying problem.

The [.HELP] directory contains the default English language, on-line, content-sensitive help files. These contain the help information and HTML markup. Each file name contains an indication of the language, where the English version might be HELP_EN.HTML, the French language version HELP_FR.HTML, etc. These files are dynamically accessed and composed by soyMAIL when a user accesses on-line help. The users language option is used to search for a possible file with that language indicated in the name. If not found it supplies the default English language version. One or (preferably) all of each of the help topic files can be copied to a language-specific instance and translated. As with message files please make any such resources available to the general soyMAIL community.

## 5.2 Site

The soyMAIL configuration file has several directives intended to allow site-specific information to be included in soyMAIL pages at appropriate locations.

- [help-about-site]
- [help-local-text]
- [message-list-footer]
- [page-title]
- [page-title2]
- [print-header]
- [print-footer]
- [soymail-at-title]

The SMTP host and apparent source of messages can be specified.

- [SMTP-server-host]
- [SMTP-from-host]

The obviously VMS-specific portions of soyMAIL (e.g. the VMS options panel, the extract button) may be 'hidden'.

- [VMS-occluded]

##### Local User Option Defaults

Users options may be defaulted and overridden.

- [user-options-default]
- [user-options-override]

For example; to provide a language default other than English, perhaps German:

[user-options-default] [language] de

To force a site to use a particular (perhaps corporate) theme

[user-options-override] [theme] _draco_corp

The user option to specify a "From:"address line can be disabled with

[user-options-override] [SMTP-from] <span style="text-decoration: none">!</span>

##### Two Notes

- The user-option directives used as parameters in these examples must be escaped.
- Themes beginning with an underscore will never be overwritten by a soyMAIL update. soyMAIL never will include themes beginning with an underscore.

##### Local Help

In addition a site-specific help file can be created in the [.HELP] directory. It must be named SITE_language>.HTML (note the leading underscore, which means it will not be overwritten by a soyMAIL update, and the language component). If this file is found during help composition it is appended to the primary help page (that obtained in help by using the [help] button) and is intended for providing site information and/or links of local relevance.

## 5.3 User

The options button in the main menu provides on-line access to user option settings.

In addition there are some less commonly used options that must be manually edited into the options file. The file is named SOYMAIL_OPTIONS.TXT and located in the user's mail area (with MAIL.MAI). Once inserted they are propagated during on-line option changes.

Directive | Description
--- | ---
[accessability-1] | enables a heavy underscore beneath each line of the message listing (accessability [sic] :-)
[message-attachment-panel] | 0 below the message (default), 1 above
[options-panel-expand] | 0 user options panels 'just wide enough', 1 panels 100% of main panel (Wm(B)K special :-)
[preview-size] | the maximum number of characters displayed in a message preview (default 1024)

# 6.soyMAIL User Files

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

soyMAIL creates and maintains several files in the same directory as the users MAIL.MAI file. The names are all prefixed with SOYMAIL_ (an underscore). Needless-to-say these files should not be deleted or edited without good reason and care. Doing so potentially disrupts the users soyMAIL environment. Some, all, multiple instances, or none of these may be present at any given time.

Filename | Purpose
--- | ---
SOYMAIL_nnnnnnnnnnnnnnnn.ATT | Binary content attachment file either saved from a message or uploaded via the composition page.
SOYMAIL_CONTACTS.LDIF | LDAP Data Interchange Format (LDIF) file containing users contact and address information.
SOYMAIL_DRAFT.TXT | Not used with v1.3 or later.
SOYMAIL_OPTIONS.TXT | Plain text configuration file storing the users option settings.
SOYMAIL_SIGNATURE.TXT | Plain text file containing the soyMAIL-specific signature.
SOYMAIL_SIGNATURE_*.TXT | User-created signatures (as above).
SOYMAIL_YOUGOTMAIL.MP3 | Binary audio file containing users optional "you've got mail" audible alert.

##### Extracted Files

The soyMAIL message read attachment (message part) extract button (where not VMS-occluded) allows message components to be written to the VMS user account home directory. All files created have the name prefixed with SOYMAIL- (a hyphen) and the rest generated from the attachment/part name. If that part name contains a file type (e.g. .GIF, .PDF, .TXT) then that is used in the name. If it does not contain such a type then soyMAIL attempts to generate one from the MIME content-type.

MIME Content Type | VMS Record Format | Generated Extension
--- | --- | ---
text/plain | stream-LF | TXT
text/html | stream-LF | HTML
text/.. | stream-LF | none
message/rfc822 | stream-LF | .LIS
message/.. | stream-LF | none
anything else | fixed 512 | none

# 7.Miscellaneous Topics

7.1 Run-time Problem Solving
7.2 Inconsistent State Data
7.3 Site Contact / Mailing Lists
7.4 General Access To Help

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

Miscellaneous soyMAIL features and other topics.

## 7.1 Run-time Problem Solving

When an error is reported, either fatal or in the status panel, the source code module name and line number of the reporting point is included as an HTML comment (the page source needs to be opened and searched) to assist in locating and rectifying issues.

<!-- ***** REPORTING MODULE:LINE IS MESSAGE:2822 ***** -->
Please include this information when reporting problems.

Defining the system-level logical name SOYMAIL$WATCH to either TRUE or the IP address of the client to be observed provides a plain-text report designed to assist in solving configuration or software issues with soyMAIL.

## 7.2 Inconsistent State Data

To prevent data corruption and inconsistent behaviours soyMAIL performs integrity checks on the state data it propagates from request to request. It is possible for a user session spanning a soyMAIL update (version release) to see the following error status message.

Inconsistent state data (version). Restarting session.

This is of no concern. The change in version has been noted by the software and to prevent any potential inconsistencies in data structures causing subtle or gross problems it has reinitialized the state data resulting in an effectively empty session. The user should just reopen (<u>not</u> refresh/reload) the particular page.

The second variation of this message is a little more concerning.

Inconsistent state data (corruption). Restarting session.

soyMAIL maintains a hash of the state data which is propagated with it. The hash is recalculated and compared at the next request. This error reports the comparison failed and indicates data corruption in the request state. The session is effectively emptied as a precautionary measure. Instances of this message should be very rare and if persistent carefully investigated.

## 7.3 Site Contact / Mailing Lists

The logical name SOYMAIL_CONTACT_LIST can be used to specify a logical list of contact lists (in addition to any personal contacts). This functions as a multi-value logical name with each value being the logical name for, or actual file specification of, an LDIF list or a traditional VMS-style mailing list (each line in the file contains a single address). For example:

$ DEFINE /SYSTEM SOYMAIL_CONTACT_LIST - ALL_USERS_LIST,GROUP1_USERS_LIST,GROUP2_USERS_LIST,GROUP3_USERS_LIST,- EXTERNAL_LIST,MAILING_LIST_LIST

Where ALL_USERS_LIST is a VMS-style, so are GROUP1_USERS_LIST and GROUP2_USERS_LIST. MAILING_LIST_LIST is a file containing a VMS-style mailing list of the mailing lists supported by the system. For the above it might contain five lines with:

ALL_USERS_LIST GROUP1_USERS_LIST GROUP2_USERS_LIST GROUP3_USERS_LIST EXTERNAL_LIST

These can then be selected to mail to the entire list.

##### LDIF Address Lists

Even large LDIF address lists (hundreds or thousands of items), such as might be exported from corporate MS Exchange servers, can be loaded relatively efficiently by soyMAIL. This can be further improved through processing the list using soyMAIL as a command-line utility.

$ MCR <location>:SOYMAIL /LDIF=PURGE <input-file-name> <output-file-name>

This purges all but soyMAIL relevant elements from the data.

## 7.4 General Access To Help

Context-sensitive help is available to authenticated users accessing private mail. A page built from the consolidated help information (and distinctly resembling the print page for context-sensitive help) is available for unauthenticated (general) access. Use the following URL to access this page.

http://the.host.name/cgi-bin/soymail?help

# 8.Index

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

A | 4.7 Access Log
| 2.2 Apache (SWS)
| ‘Apache License, Version 2.0’ in soyMAIL
| 2.1 Authentication
| 4. Autogenous Authentication
C | ‘CAUTION...’ in 2.5 SMTP Relay
| ‘CGIplus’ in 2.4 WASD
| 4.6 CHANGE.HTML
| ‘Checking Regular Expressions’ in 3.13 Regular Expression Overview
| 3.12 Conditional Configuration
| ‘Conditional Configuration Example’ in 3.12 Conditional Configuration
| 3. Configuration
| 4.1 Configuration
| 5. Customization
D | 3.1 Directives
E | ‘Equivalent Regex Example’ in 3.12 Conditional Configuration
| 4.4 External Authentication Agent
| ‘Extracted Files’ in 6. soyMAIL User Files
G | 7.4 General Access To Help
H | 2.6 HTML Editor
I | 7.2 Inconsistent State Data
| 8. Index
| 2. Installation
| ‘Installation and Administration’ in soyMAIL
| 1. Introduction
J | ‘JavaScript required’ in 1. Introduction
K | ‘Keyword Example’ in 3.12 Conditional Configuration
L | ‘LDIF Address Lists’ in 7.3 Site Contact / Mailing Lists
| ‘License’ in soyMAIL
| ‘Link-only’ in 2. Installation
| ‘Local Help’ in 5.2 Site
| ‘Local User Option Defaults’ in 5.2 Site
| 5.1 Locale
| 4.3 Login Alias
| 4.5 LOGIN.HTML
M | 7. Miscellaneous Topics
O | 2.3 OSU
P | 4.2 Password Change
| ‘Postmaster’ in 3.6 [private-access]
| ‘Proctor’ in 2.4 WASD
R | ‘Regex Equivalents of Common Wildcards’ in 3.12 Conditional Configuration
| 3.13 Regular Expression Overview
| ‘Run-time Components’ in 2. Installation
| 7.1 Run-time Problem Solving
S | 5.2 Site
| 7.3 Site Contact / Mailing Lists
| 2.5 SMTP Relay
| ‘soyMAIL’ in soyMAIL
| ‘Surprisingly Capable Web-mail for OpenVMS’ in soyMAIL
T | ‘Table of Content’ in soyMAIL
| ‘Tests’ in 3.12 Conditional Configuration
| ‘Two Notes’ in 5.2 Site
U | ‘Update’ in 2. Installation
| 5.3 User
W | 2.4 WASD
Y | ‘yahMAIL’ in 1. Introduction

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎