↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |
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
Comments, directive names and directive data can be seen.
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) |
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
The following example provides a selection of Arabic, Greek and Hebrew.
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.
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:
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:
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:
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:
the soyMAIL configuration would be set
The soyMAIL configuration directive may also be set to a single hyphen to disable the logout button and functionality.
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
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
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.
Using the same mechanism a non-VMS-account remote user may be mapped into the mail of an existing VMS username.
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 violation” fatal error). For example
This postmaster can then do anything using soyMAIL the specified username can do. Such an account is flagged in the following manner.
Note that POSTMASTER here is not an account. It is a soyMAIL characteristic flagged against the username. The parentheses are required.
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.
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.
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).
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
Both wildcard variants allow an initial folder to be specified
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.
The first rule would map the URL
The third rule maps the URL
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.
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 :-) |
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.)
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.
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. |
asterisk ('*') | matches zero or more characters | period then asterisk ('.*') |
question mark ('?') | matches any single character | period ('.') |
Percentage ('%') | matches any single character | period ('.') |
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 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.
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 |
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.
↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |