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
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.
A link-only build has the following alternate steps which can be used in any environment described below.
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.
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.
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.
This installation information is per SWS version 2.1. If you have a different version the requirements may require adjustment.
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:
Depending on the planned authorization source it may also be necessary to check that the OpenVMS authorization module is configured.
Private access URI:
It is suggested to place the soyMAIL kit under WWW_ROOT:[000000].
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:
Private access URI:
With WASD the soyMAIL kit occupies the usual location for source under the WASD_ROOT:[SRC] directory.
File | Location |
---|---|
SOYMAIL.EXE | WASD_ROOT:[<arch-bin>-BIN] |
SOYMAIL_STARTUP.COM | WASD_ROOT:[STARTUP] |
SOYMAIL.CONF | WASD_ROOT:[LOCAL] |
Mapping and authorization examples:
Private access URI:
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.
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.)
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.
And an entry placed in the plain-text configuration to enable access for allowed SMTP clients (the 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.
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):
↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |