|set|chunked=0|
|set|toc=cols=2|
|set|toc=format=1………………|

|style|default|
|style|._soymail \
{ font-family: "Lucida Console", Monaco, monospace; letter-spacing:-0.05em; }
h1 ._soymail { font-family: "Lucida Console", Monaco, monospace; }|
|style|.button { border: 1px gray solid; border-radius:3px; \
padding:0.1em; margin:0.1em; font-size:90%; } ||
|style|.smiley::after \
{ font-size:150%; vertical-align:middle; content:'\\263a' }|
|style|.frowny::after \
{ font-size:150%; vertical-align:middle; content:'\\2639' }|

|01'_soymail&font-size:160%;.soyMAIL|
|02Surprisingly Capable Web-mail for OpenVMS|
|03Installation and Administration|

|^ Published February 2024 for |'_soymail.soyMAIL| v2.1.0

|^ Document generated using |'wasdoc.wasDOC| |insert|wasdoc=version|

|^ |*'_soymail.soyMAIL| |-| |*Copyright \© 2005-2024 Mark G. Daniel|

|9Apache License, Version 2.0|
|9License|
|^ Licensed under the |*Apache License||, Version 2.0 (the "License");
|quote&font-size:0.9em;width:49em;margin:-0.5em 0 0 1em;|
you may not use this software except in compliance with the License.
You may obtain a copy of the License at
|^ |link%&margin-left:1em;|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.
|!quote|

|^ |mailto: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.soyMAIL| is available for download from
|^+ |%http://wasd.vsm.com.au/wasd/|

|^ Release notes for this version:
|^+ \<a class=\"link\" target=\"_blank\" href=\"../release_notes.txt\"\>\
../release_notes.txt\</a\>

|01&font-size:120%;.Table of Content|

|toc|

|1Introduction|

|9yahMAIL|
|^ |'_soymail.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.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.soyMAIL| is a more than
worthy successor as the 'son of |=yahMAIL||'.

|^ |'_soymail.soyMAIL| has been developed against these VMS Web server
environments

|bullet#|
|& Apache (SWS) 2.2 and 1.3
|& OSU 3.10
|& WASD 12.|/n||,11.|/n||, 10.|/n||, 9.|/n|
|!bullet|

for building and use on all VMS platforms

|bullet#|
|& Alpha
|& Itanium
|& x86-64
|& (VAX is no longer supported)
|!bullet|

and versions of VMS from V7.0 onwards.

|^ |'_soymail.soyMAIL| supports 

|bullet#|
|& 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) 
|!bullet|

|^ |'_soymail.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.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.

|9JavaScript required|
|^ |'_soymail.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.|

|1Installation|

|^ |'_soymail.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
|link|Run-time Problem Solving| when troubleshooting an installation.

|^ |'_soymail.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

|mono|
SOYMAIL200.ZIP
SOYMAIL200-AXP.ZIP
SOYMAIL200-IA64.ZIP
SOYMAIL200-VAX.ZIP
|!mono|

|^ 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. 

|0Link-only|

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

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

|0Update|

|^ 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.

|code|
$ @INSTALL UPDATE <server>
|!code|

|0Run-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.

|table|
|~_ |: 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
|!table|

|^ 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.

|2Authentication|

|^ |'_soymail.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.soyMAIL|
autogenous login and state management.  See |link|Autogenous Authentication||.

|2Apache (SWS)|

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

|code|
$ SET DEFAULT APACHE$ROOT:[000000]
$ UNZIP <span style="font-style: normal">device:[dir]SOYMAILnnn.ZIP</span>
$ SET DEFAULT [.SOYMAIL]
$ @BUILD_SOYMAIL
$ @INSTALL INSTALL APACHE
|!code|

After installation files are located as follows.

|table|
|~_ |: 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] 
|!table|

|^ 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:

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

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

|code|
LoadModule  auth_openvms_module  modules/mod_auth_openvms.exe
|!code|

|^ Private access URI:

|code|
/cgi-bin/soymail/~
|!code|

|2OSU|

|^ It is suggested to place the |'_soymail.soyMAIL| kit under WWW_ROOT:[000000].

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

|^ After installation files are located as follows.

|table|
|~_ |: File |: Location
|~ 
|~= |. SOYMAIL.EXE |. WWW_ROOT:[BIN] 
|~= |. SOYMAIL_STARTUP.COM |. WWW_ROOT:[SYSTEM] 
|~= |. SOYMAIL.CONF |. WWW_ROOT:[CONF] 
|!table|

|^ Mapping and authorization examples:

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

|^ Private access URI:

|code|
/htbin/soymail/~
|!code|

|2WASD|

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

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

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

|^ Mapping and authorization examples:

|code|
# 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
|!code|

|^ Private access URI:
|code|
/cgi-bin/soymail/~
|!code|

|0CGIplus|

|^ WASD provides the persistent scripting environment CGIplus. 
|'_soymail.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.soyMAIL| into CGIplus space prior to other
|'_soymail.soyMAIL| required rules.

|code|
# WASD_CONFIG_MAP
redirect /cgi-bin/soymail* /cgiplus-bin/soymail*
|!code|

|0Proctor|

|^ |'_soymail.soyMAIL| may be proctored (not sure what this means? |--|
check section "Script Proctor" in "WASD Scripting Environment" document).

|code|
# WASD_CONFIG_GLOBAL
[DclScriptProctor]
1 /cgiplus-bin/soymail /cgiplus-bin/soymail
|!code|

|2SMTP Relay|

|^ |'_soymail.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.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.)

|note><|
|0CAUTION...|
|...||*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!
|!note|

|^ 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.soyMAIL| script.  The configuration option to enable relaying must be
set.

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

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

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

|^ The SMTP server that the |'_soymail.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 |link|Directives||) can be
used to specify and alternate host name or IP address (and non-default port if
required) for |'_soymail.soyMAIL| to connect to.

|2HTML Editor|

|^ TinyMCE is supplied as an integrated element of |'_soymail.soyMAIL||. 
Although |'_soymail.soyMAIL| itself has no specific requirement for installation
on an ODS-5 volume, TinyMCE has file names containing multiple periods. 
UNZIPing the |'_soymail.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.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):

|code|
# 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/*
|!code|

|1Configuration|

|^ |'_soymail.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

|code|
########################
# 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]
|!code|

|^ Comments, directive names and directive data can be seen.  

|2Directives|

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

|table|
|~_ |:&width:15em;.Directive |: Description
|~ 

|~#* |. |=.[access-log]| |. generates a soyMAIL-specific access log file when
autogenous authentication is in use (see |link|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 |link|[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
|link|Autogenous Authentication||) 

|~ |. |=.[login-acme-no-restrict]| |. ignore any login source restriction (e.g.
/NONETWORK) provided authentication was successful (see section
|link|Autogenous Authentication||) 

|~ |. |=.[login-agent]| |. external, site-provided authentication agent (see
|link|Autogenous Authentication||) 

|~ |. |=.[login-alias]| |. mapping from user-supplied user-name string to
username used for autogenous authentication (see |link|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 |link|Autogenous Authentication||) 

|~ |. |=.[login-change-page]| |. file-system location for password change page
(see |link|Autogenous Authentication||) 

|~ |. |=.[login-idle]| |. seconds idle before credential reentry (see
|link|Autogenous Authentication||) 

|~ |. |=.[login-language]| |. language for login page (see |link|Autogenous
Authentication||)

|~ |. |=.[login-no-pwdexp]| |. ignore expired passwords (see section
|link|Autogenous Authentication||)

|~ |. |=.[login-page]| |. file-system location for login page (see section
|link|Autogenous Authentication||) 

|~ |. |=.[login-secret]| |. encryption key for credential cookie (see
|link|Autogenous Authentication||) 

|~ |. |=.[login-type]| |. integer representing NETWORK, LOCAL, REMOTE, etc.
(see |link|Autogenous Authentication||) 

|~ |. |=.[login-verify]| |. seconds between credential verification (see
|link|Autogenous Authentication||) 

|~ |. |=.[logout-realm]| |. enables the logout button and functionality (see
|link|[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 |link|[private-access]||) 

|~ |. |=.[private-request]| |. indicates this request is for private access
(see |link|[private-request]||)  

|~ |. |=.[public-access]| |. permits and maps request path strings to VMS Mail
user names, mail file and folders (see |link|[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 |link|[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 |link|[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 |link|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) 

|!table|

|2.[compose-charsets]|

|^ By default |'_soymail.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.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

|mono|
|/description| = [<] |/charset-name|
|!mono|

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.

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

|^ 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.

|2.[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:

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

|^ 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:

|code|
[smtp-from] !
|!code|

|2.[html-editor-load]|

|^ |'_soymail.soyMAIL| supports plug-in JavaScript HTML editors for HTML message
composition.

|^ TinyMCE is provided as part of the |'_soymail.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:

|code|
[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! */ }
|!code|

|2.[logout-realm]|

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

|^ The |'_soymail.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.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:

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

|^ the |'_soymail.soyMAIL| configuration would be set

|code|
[logout-realm]  VMS account
|!code|

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

|2.[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.soyMAIL| autogenous authentication (section
|link|Autogenous Authentication||).  If there is no browser username/password
dialog, or no login page, then it's not configured correctly!|

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

|code|
/cgi-bin/soymail/~
|!code|

|^ Alternatively, a site-specific private sentinal can be configured using the
[private-request] configuration directive (see |link|[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

|code|
<remote-user>/<realm>/<vms-username>
|!code|

|^ 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.

|code|
*/*/*
|!code|

|^ 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.

|code|
[private-access]
system/*/_system
another/*/_another
*/*/*
|!code|

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

|code|
[private-access]
freddo/*/nurkf
jd/*/doej
*/*/*
|!code|

|0Postmaster|

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

|code|
/cgi-bin/soymail/~daniel/
|!code|

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

|code|
[private-access]
whomever/*/(POSTMASTER)
*/*/*
|!code|

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

|2.[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 |link|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.

|code|
[if-CGI-remote_user]
[private-request]
[end-if]
|!code|

|^ This effectively directs |'_soymail.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.soyMAIL|
executable.

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

|^ 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.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). 

|2.[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

|code|
/<public-path>/ /<username>/<mail-file>/<folder-name>/
|!code|

with the full wildcard variant

|code|
/<public-path>/ /<username>/<mail-file>/*/
|!code|

and the prohibited MAIL and NEWMAIL wildcard variant

|code|
/<public-path>/ /<username>/<mail-file>/*!/
|!code|

|^ Both wildcard variants allow an initial folder to be specified

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

|^ 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.

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

|^ The first rule would map the URL

|code|
http://the.host.name/cgi-bin/soymail/an_example/
|!code|

to VMS account NURKF, the default mail file MAIL.MAI and the PUBLIC folder in
that.  The second rule maps the URL

|code|
http://the.host.name/cgi-bin/soymail/another_example/
|!code|

to the JOED account, mail file ARCHIVE.MAI and folder MAIL in it.

|^ The third rule maps the URL

|code|
http://the.host.name/cgi-bin/soymail/public/
|!code|

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.

|2.[search-control]|

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

|bullet|

|item| 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.

|item| 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.

|!bullet|

|^ 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.

|table|
|~_ |:&width:10em;.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 :-) 
|!table|

|2.[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.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.)

|2.[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||.

|2Conditional Configuration|

|^ |'_soymail.soyMAIL| has a useful facility allowing dynamic configuration of
|'_soymail.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.

|table|
|~_ |:&width:10em;.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.  
|!table|

|0Keyword Example|

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

|0Equivalent Regex Example|

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

|0Regex Equivalents of Common Wildcards|

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

|0'Boolean' 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.

|code|
[if-CGI-|/<variable_name>||]
|!code|

|^ 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.

|code|
[if-not-CGI-|/<variable_name>||]
|!code|

|0Conditional Configuration Example|

|code|
# 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]
|!code|

|2Regular Expression Overview|

|^ |'_soymail.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|

|table|
|~_ |:&width:15em;.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. |=\\ ^ . $ \| [ (| 
|!table|

|^ 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.

|table|
|~_ |: 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  
|!table|

|^ 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.

|table|
|~_ |: 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   
|!table|

|0Checking Regular Expressions|

|^ |'_soymail.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.soyMAIL| as a foreign verb and use as
illustrated.

|code|
$ SOYMAIL /REGEX  <text to be matched> <pattern>
|!code|

|1Autogenous Authentication|

|^ Access to private Mail via |'_soymail.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.soyMAIL| maintain it's own authentication state.  This section
describes the latter.

|^ The main advantage in allowing |'_soymail.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! |'smiley.\ |

|^ 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||.

|^ |'_soymail.soyMAIL| authentication

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

|^ In addition |'_soymail.soyMAIL|

|bullet#|
|item| continues to verify the credentials periodically
|item| will request the credentials be reentered after an idle period
|!bullet|

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

|bullet|

|item| 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.

|item| 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.

|!bullet|

|^ 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.soyMAIL||.  To restrict an account it
is necessary to deny access using the [private-access] directive (section
|link|[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.

|2Configuration|

|^ If Web server authorization for |'_soymail.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.soyMAIL| configuration directive [login-secret].  This is used as a
key to encrypt the |'_soymail.soyMAIL| credential cookie value.  When this
directive has a value against it |'_soymail.soyMAIL| attempts to establish it's
own authentication state.  As this is an encryption key care should be taken to
ensure it is

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

|^ An |_example| configuration might be

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

|2 Password Change|

|^ |'_soymail.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.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 |link|CHANGE.HTML||). Using the default file that would be

|code|
[login-change-page]  SOYMAIL_THEME:CHANGE.HTML
|!code|

|^ As with authentication password change is either performed by ACME or a
|'_soymail.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.

|table|
|~ |. |=.[login-type] 3| |. LOCAL 
|~ |. |=.[login-type] 4| |. DIALUP 
|~ |. |=.[login-type] 5| |. REMOTE 
|!table|

|2Login 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.

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

|^ 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 "*/-".

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

|^ 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|

|2External Authentication Agent|

|^ This provides a site-specific, external-to-|'_soymail.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

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

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

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

|^ 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.

|code|
$ 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
|!code|

|^ This would probably be more like a working one.

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

|2LOGIN.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.soyMAIL| configuration.

|code|
[login-page]  SOYMAIL_THEME:_LOGIN.HTML
|!code|

|2CHANGE.HTML|

|^ The HTML used by the password change page (see |link|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.

|2Access 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.soyMAIL| is often useful or mandatory audit information and so
|'_soymail.soyMAIL| provides this as a supplemental access log file.

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

|code|
[access-log]  WASD_LOGS:SOYMAIL.LOG
|!code|

|^ To assist in the maintenance of such logs |'_soymail.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.soyMAIL| access log file name use

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

|^ 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.

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

|^ |'_soymail.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.

|1Customization|

|^ |'_soymail.soyMAIL| provides three levels of customization.

|bullet#|
|item| locale
|item| site
|item| user
|!bullet|

|2Locale|

|^ 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.soyMAIL| configuration file are for this purpose.  The language files
are global components of the |'_soymail.soyMAIL| distribution.

|^ If you wish to put a language-specific message file together for
|'_soymail.soyMAIL| please contribute it back into the |'_soymail.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.soyMAIL| reports a  message file fatal
error the SOYMAIL$WATCH facility (see |link|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.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.soyMAIL| community.

|2Site|

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

|simple#|
|& |=.[help-about-site]|
|& |=.[help-local-text]|
|& |=.[message-list-footer]|
|& |=.[page-title]|
|& |=.[page-title2]|
|& |=.[print-header]|
|& |=.[print-footer]|
|& |=.[soymail-at-title]|
|!simple|

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

|simple#|
|& |=.[SMTP-server-host]|
|& |=.[SMTP-from-host]|
|!simple|

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

|simple#|
|& |=.[VMS-occluded]|
|!simple|

|0Local User Option Defaults|

|^ Users options may be defaulted and overridden.

|simple#|
|& |=.[user-options-default]|
|& |=.[user-options-override]|
|!simple|

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

|code|
[user-options-default]
\[language]  de
|!code|

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

|code|
[user-options-override]
\[theme] _draco_corp
|!code|

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

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

|0Two Notes|

|bullet|
|& 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.
|!bullet|

|0Local 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.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.

|2User|

|^ 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.

|table|
|~_ |:&width:18em;.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) 
|!table|

|1 |'_soymail.soyMAIL| User Files|

|^ |'_soymail.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.soyMAIL| environment.  Some, all, multiple instances, or none of
these may be present at any given time.

|table|
|~_ |:&width:15em;.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.
|!table|

|0Extracted Files|

|^ The |'_soymail.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.soyMAIL| attempts to generate one from the MIME content-type.

|table|
|~_ |:&width:10em;.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|
|!table|

|1 Miscellaneous Topics|

|^ Miscellaneous |'_soymail.soyMAIL| features and other topics.

|2Run-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.

|code|
<!-- *****  REPORTING MODULE:LINE IS MESSAGE:2822  ***** -->
|!code|

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.soyMAIL||.

|2Inconsistent State Data|

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

|code|
Inconsistent state data (version).  Restarting session.
|!code|

|^ 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.

|code|
Inconsistent state data (corruption).  Restarting session.
|!code|

|^ |'_soymail.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.

|2Site 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:

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

|^ 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:

|code|
ALL_USERS_LIST
GROUP1_USERS_LIST
GROUP2_USERS_LIST
GROUP3_USERS_LIST
EXTERNAL_LIST
|!code|

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

|0LDIF 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.soyMAIL||.  This can be further improved through
processing the list using |'_soymail.soyMAIL| as a command-line utility.

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

|^ This purges all but |'_soymail.soyMAIL| relevant elements from the data.

|2 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.

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

|1Index|

|index|