NOTE: SOME FUNCTIONALITY EMPLOYS JAVASCRIPT soyMAIL – 2. Installation

soyMAIL

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.1Authentication

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.2Apache (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/~
SWS 2.0 and 2.1 Note

There is an issue with SWS 2.0 and 2.1 when POSTing request bodies greater than 64kB.
This issue has been fixed with SWS V2.1-1 released 27th September 2006.

2.3OSU

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/~</pre><h2 class="western">

2.4WASD

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 /cgi-bin/soymail/~* map=once # 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*

2.5SMTP 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.6HTML 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/*