>I  soyMAILE 2 . 2 N  &

&

¨

soyMAIL

y

Enterprise-classWeb-mail for OpenVMS

(





Installation

D

3and

Administration

R

!Copyright

I

Copyright ©2005-2008 Mark G. Daniel

>

This program, documentation, and associated0resources, come with ABSOLUTELY NO WARRANTY.

@

This is free software, and you are welcome to>redistribute it under the conditions of the GNU GENERAL PUBLIC-LICENSE, version 3, or any later version.

_

http://www.gnu.org/licenses/gpl.html

@

All trademarks within this document belong totheir legitimate owners.







U

Author

0

Mark G. Daniel

c

Mark.Daniel@wasd.vsm.com.au

=

A pox on the houses of all-SPAMers. Make that two poxes.

x

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







W

Download

A

The latest release of soyMAIL is available fordownload from

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







O

Publication$date and software version

E

Published October 2008. Based on soyMAIL v1.5







]

OpenOffice.org

8

This document has been produced usingOpenOffice.org 3.0 Writer

Q

http://openoffice.org/

=





G
-
N

Table of Contents


n

1' Introduction 1

n

2' Installation 3

ˆ

2.1) Authentication 4

2.2' Apache (SWS) 4

}

2.3 OSU 5

2.4# Purveyor 5

~

2.5 WASD 6

2.6% SMTP Relay 7

o

3( Configuration 8

3.1% Directives 8

Œ

3.2. [compose-charsets] 11

3.3/ [compose-user-from] 11

Œ

3.4. [html-editor-load] 12

ˆ

3.5* [logout-realm] 13

Š

3.6, [private-access] 14

3.7- [private-request] 15

3.8+ [public-access] 16

Š

3.9, [search-control] 17

3.10/ [smtp-default-host] 17

3.11/ [update-last-login] 18

3.125 Conditional Configuration 18

3.137 Regular Expression Overview 19

{

45 Autogenous Authentication 22

4.1) Configuration 23

4.2+ Password Change 23

4.3' Login Alias 23

4.49 External Authentication Agent 24

4.5& LOGIN.HTML 25

4.6' CHANGE.HTML 25

4.7& Access Log 25

o

5) Customization 27

5.1" Locale 27

~

5.2 Site 27

~

5.3 User 29

t

6. soyMAIL User Files 30

v

70 Miscellaneous Topics 31

7.14 Run-time Problem Solving 31

7.23 Inconsistent State Data 31

7.38 Site Contact / Mailing Lists 31

7.42 General Access To Help 32




[

1 Introduction

B

soyMAIL is a native VMS application thatDexecutes as an HTTP server script providing authenticated Web accessEto an account's VMS Mail. All that is required at the client end is aC(relatively) modern browser supporting CSS2 (Cascading Style SheetsB2). JavaScript significantly enhances the functionality of soyMAIL?but is not essential to its use. HTTP cookies are required forautogenous authentication.

E

soyMAIL has been built on experience gained@hacking about with its progenitor yahMAIL but unlike yahMAIL wasDdesigned from the start to satisfy all the basic requirements for an=enterprise-class Web-based email interface. It is theDauthor's (perhaps) humble opinion that soyMAIL is a more than worthy<successor as the 'son ofyahMAIL'.

B

soyMAIL has been developed against these browsers

9

additionally reported to work with

8

these VMS Web server environments

B

designed to be suitable for building and use onall VMS platforms

=

and versions of VMS from V6.0 onwards.

+

soyMAIL supports 

2




O

soyMAIL_has a privateDaccess mode that allowsDauthenticated access to an underlying VMS account's email facility. CThis is where it provides the 'classic' web-mail functionality. ItBalso provides a public>access mode whichBrequires no authentication (though it is not forbidden either) andCprovides controlled access to a specific folder, in a specific mailDfile, in a specific VMS account, intended to allow general access to,a managed subset of a users Mail.

D

soyMAIL has been carefully and extensivelyEoptimized to perform well within the general VMS environment and whenusing callable Mail.

B

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

A

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

[

2 Installation

D

soyMAILDrequires some configuration before use. It is recommended that thisDentire document be read and carefully considered before installationDand attempted usage. Please use the facilities described in sectionf7.19when troubleshooting an installation.

C

soyMAILCis distributed as a source-code/run-time resource ZIP archive, with?optional supplementary object code archives for each of the VMS9platforms. For example, version one would be packaged

/
SOYMAIL100.ZIPSOYMAIL100-AXP.ZIPSOYMAIL100-IA64.ZIPSOYMAIL100-VAX.ZIP

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

D

Brief installation and other relevant informationAcan be obtained from the archive using the UNZIP “-z” option.

X

Link-Only

@

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

C
$ 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 be9performed in any of the environments described below.

~
$ @INSTALL UPDATE <server>

+Run-time Components

=

The following table describes the run-timeDcomponents. The installation procedure described below places theseEin the default locations the startup procedure expects to find them. AOf 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.

L                                


Component




Purpose


)

[.OBJ_<arch>]SOYMAIL.EXE


=

Architecture appropriate soyMAIL script executable, to6 [CGI-BIN], [BIN], etc. depending on the server




[.HELP]


H

Help documentation, located via the logical name SOYMAIL_HELP




[.LANG]


C

Language files located via the logical name SOYMAIL_LANG




[.THEME]


C

CSS and other thematic resource files located by the logical5 name SOYMAIL_THEME and by the script via the path /soymail/-/theme/




SOYMAIL.CONF


I

Configuration file located by the logical name SOYMAIL_CONFIG.




SOYMAIL_STARTUP.COM


E

Startup procedure to define required logical names and install SOYMAIL.EXE image








D

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

E

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

T

2.1 Authentication

=

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

E

The configuration guidelines in following sectionsDcontain both file mapping and authorization configuration examples. EThe 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 section 4.

E

2.2 Apache (SWS)

C

This installation information is per SWS versionB2.1. If you have a different version the requirements may requireadjustment.

C
$ SET DEFAULT APACHE$ROOT:[000000]J$ UNZIP device:[dir]SOYMAILnnn.ZIP$ SET DEFAULT [.SOYMAIL]$ @BUILD_SOYMAIL$ @INSTALL INSTALL APACHE

4After installation files are located as follows.

L                        


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]


B


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

:

Mapping and authorization examples:

V
Alias /soymail/-/ "/apache$common/soymail/"5<Location ~ “^/cgi-bin/soymail/\~”>AuthType Basic+AuthName "OpenVMS authentication"AuthUserOpenVMS Onrequire valid-user</Location>

<Depending on the planned authorization source it may also be;necessary to check that the OpenVMS authorization module isconfigured.

^
LoadModule  auth_openvms_module  modules/mod_auth_openvms.exe

Private access URI:

}
/cgi-bin/soymail/~

3SWS 2.0 and 2.1 Note

Q

BThere is an issue with SWS 2.0 and 2.1 when POSTing request bodieshgreater than 64kB. This issue hasEbeen fixed with SWS V2.1-1 released 27thSeptember 2006.

>

2.3 OSU

A

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

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

4After installation files are located as follows.

M                    


File




Location




SOYMAIL.EXE




WWW_ROOT:[BIN]




SOYMAIL_STARTUP.COM




WWW_ROOT:[SYSTEM]




SOYMAIL.CONF




WWW_ROOT:[CONF]








:

Mapping and authorization examples:

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

Private access URI:

K
/htbin/soymail/~

42.4 Purveyor

?

Purveyor Encrypt WebServer is now explicitly<excluded from soyMAIL support. A significant issue has beenCidentified as Purveyor corrupting "text/.." response dataAwith extraneous line-feeds if the script process SYS$OUTPUT, 1024Acharacter capacity mailbox, inadvertently fills during processingH(the symptoms of which have been reported on a number of occasions).

@

Google news groups for "soymail purveyormailbox 1024".

B

There is no/possibility of this bug being fixed:

:

http://www.process.com/techsupport/maintagreement.html

@

2.5 WASD

?

With WASD the soyMAIL kit occupies the usual8location for source under the HT_ROOT:[SRC] directory. 

<
$ SET DEFAULT HT_ROOT:[SRC]J$ UNZIP device:[dir]SOYMAILnnn.ZIP$ SET DEFAULT [.SOYMAIL]$ @BUILD_SOYMAIL0$ @INSTALL INSTALL WASD





G

After installation files are located as follows.

M                    


File




Location




SOYMAIL.EXE


%

HT_ROOT:[<arch>-BIN]




SOYMAIL_STARTUP.COM




HT_ROOT:[STARTUP]




SOYMAIL.CONF




HT_ROOT:[LOCAL]


2




:

Mapping and authorization examples:

2




,
# HTTPD$MAP(pass /soymail/-/* /ht_root/src/soymail/* set /cgi-bin/soymail/~* map=once# HTTPD$AUTH["description"=REALM]/cgi-bin/soymail/~* r+w

Private access URI:

o
/cgi-bin/soymail/~

82.6 SMTP Relay

<

soyMAILCoriginates 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. TheAconfiguration for allowing relay varies on the TCP/IP and/or mailBpackage in use (i.e. TCP/IP Services, MultiNet, TCPware, MX, PMDF,etc.) 

|

Cautionƒshould be exercised when changing configuration to allow relay.C
The last thing that you need as a result is an open relay being.used for SPAM propagation!

E





9

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

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

DAnd 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 commonlyDrunning on the same (VMS) system as the script. It does not need toEbe. The configuration directive [SMTP-server-host] (section 3.1) can=be used to specify and alternate host name or IP address (and<non-default port if required) for soyMAIL to connect to.

\

3 Configuration

<

soyMAIL configuration is provided using aBplain-text file located using the logical name SOYMAIL_CONFIG. The:configuration file must exist or all access is denied. TheDinstallation procedure copies an example configuration file allowing@private access and requiring some customization. Updates do notDsubsequently change this file. Comments may be included by prefixingCthe line with a '#' character. Each directive name is delimited byA'[' and ']' characters and directive parameters comprise all textEuntil the next comment or directive opening '['. Reserved charactersCmay be escaped using the backslash character. Leading and trailingDwhite-space is trimmed. Comments and directives must begin in column1.

D

A typical configuration file might look somethinglike

x
########################W# private soyMAIL accessW########################K[if-private]V[private-access]  */*/*][page-title]  The Company NameY[page-title2]  IT ServicesT[message-list-footer]ˆ<CENTER>~ IT Services can be contacted on 82596189 ~</CENTER>^[print-header] The Company Names[print-footer] ~ Internet, E-mail and Web Services ~P[help-about-site]ä<B><A HREF="http://the.host.name/">The Company Name</A></B> providesOpenVMS consultancy, programming and support, along with Web and Mail hosting.D[end]

;Comments, directive names and directive data can be seen. 

L

3.1 Directives

@

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

L                                                                                                                                                                                                                    


Directive




Description




[access-log]


C

generates a soyMAIL-specific access log file when autogenous2 authentication is in use (see section 4.7)


"

[attachment-mime-types]


D

Comma-separated MIME types a browser will display in-window. : Others will always be opened in a separate window.




[compose-charsets]


>

comma-separated list of character sets available on the2 message composition page (see section 3.2)


#

[compose-contacts-after]


D

expand the contacts list viewport after this many entries


"

[compose-contacts-size]


.

expand to this number of lines (em)




[compose-edit-cols]


D

comma-separated integers providing the steps the message edit0 window columns increment; e.g. 78,96,132




[compose-edit-rows]


D

comma-separated integers providing the steps the message edit, window rows increment; e.g. 20,30,40




[compose-user-from]


N

When ENABLED allows the user to specify the message “From:”@ header line. When DISPLAY just displays it on the page.




[compose-wrap-at]


C

comma-separated integers providing the steps after which the6 message text should be wrapped; e.g. 78,96,132




[disk-quota-percent]


E

With each folder opened soyMAIL checks the users consumed diskE quota. When it exceeds this percentage it adds a notification to@ the status information. Defaults to 85 percent . To disableC completely set above 100. To display permanently set to 0.




[downtime]


A

string disables the use of soyMAIL and gives the specifiedF string as a simple announcement to users connecting to soyMAIL




[font-family-local]


B

Additional font families presented in the user options font selector. One per line.




[greeting]


@

Message presented in the status panel when a client firstD accesses soyMAIL, or its help or about pages. Can0 be used as a welcome or warning message.




[help-about-site]


G

site-specific information presented on the Help 'About' page




[html-editor-load]


>

JavaScript to load and instantiate the HTML editor (see section 3.4)




[include-file]


B

Include and process the specified configuration file at theA point of inclusion. Included files may be nested up to threeE deep. Just remember, each configuration file is one that must be; read from the file-system for each soyMAIL request!




[login-acme-doi]


8

ACME domain of interpretation (see section 4)


#

[login-acme-no-restrict]


E

ignore any login source restriction (e.g. /NONETWORK) provided4 authentication was successful (see section 4




[login-agent]


G

external, site-provided authentication agent (see section 4)




[login-alias]


C

mapping from user-supplied user-name string to username used5 for autogenous authentication (see section 4)


"

[login-alias-smtp-from]


>

when ENABLED and building a compose self addressD (“From:”) use any mapped alias as the local part




[login-autocomplete]


G

browser auto-completion of login credentials (see section 4)




[login-change-page]


H

file-system location for password change page (see section 4)




[login-idle]


A

seconds idle before credential reentry (see section 4)




[login-language]


2

language for login page (see section 4)




[login-no-pwdexp]


3

ignore expired passwords (see section 4)




[login-page]


>

file-system location for login page (see section 4)




[login-secret]


?

encryption key for credential cookie (see section 4)




[login-type]


E

integer representing NETWORK, LOCAL, REMOTE, etc. (see section 4)




[login-verify]


B

seconds between credential verification (see section 4)




[logout-realm]


I

enables the logout button and functionality (see section 3.5).



[message-list-footer]


D

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-title2]


D

the text in [page-title] is forced left and the [page-title2] text is forced right




[print-header]


0

text header for printed mail messages




[print-footer]


0

text footer for printed mail messages




[private-access]


B

allows mapping between authenticated user (CGI remote-user), and a VMS username (see section 3.6)




[private-request]


I

indicates this request is for private access (see section 3.7)




[public-access]


D

permits and maps request path strings to VMS Mail user names,/ mail file and folders (see section 3.8)


#

[public-options-default]


<

allows the soyMAIL administrator to set public accessB 'personal option' settings(required to escape each leading '[' with a '\')




[public-request]


B

Indicates this request is for public access.
Complements( the [private-request] directive.




[search-control]


C

controls designed to limit the impact of intensive searching6 activity on system resources (see section 3.9)




[smtp-default-host]


D

specifies a host or domain name and makes an unqualified userD address such as Mark.Daniel into an RFC (Internet-style) addressN such as Mark.Daniel@vsm.com.au (see section 3.10)




[smtp-from-host]


;

used when constructing the 'user@from.host.name'




[smtp-server-host]


?

Host name/address of SMTP server soyMAIL connects to forE Internet mail transport (defaults to 'localhost'). A non-default6 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]


E

update SYSUAF last-login with each initial access (see section 3.11)




[user-name-info]


B

When ENABLED display on the status panel the logged-in userC name. When ALIAS (and [login-alias] in use) displays the login alias.


!

[user-options-default]


D

allows the soyMAIL administrator to preset some options (e.g.B language) by providing options configuration text against thisG directive(it is required to escape each leading '[' with a '\')


"

[user-options-override]


A

allows the soyMAIL administrator to override user selected@ options by providing options configuration text against thisH directive (it is required to escape each leading '[' with a '\')




[vms-occluded]


@

'hides' obvious VMS-specific aspects of soyMAIL (e.g. VMSC options panel, the extract button on the message read page)


b

3.2 [compose-charsets]

<

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

C

The format for each item of the directive is

C

description =[<] charset-name

C

where the description is displayed in theIlist, the optional '<' flag indicates the script directionalityHis 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 ofArabic, Greek and Hebrew.

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

9An equivalent field is available in the user options.

C

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

^

3.3 [compose-user-from]

=

When this directive is ENABLED the message@composition page provides an additional “From:” textDentry field (immediately above the “To:” field) allowing@the user to easily change the message origination (From:)Eaddress. Of course while there are legitimate uses for this facilityDit does provide potential for a certain no-brain email spoofing. IfBDISPLAY then the same field is provided for informational purposesbut cannot be modified.

A

When ENABLED it also allows one or both of twoDadditional directives to be prepended to a user signature. When theHsignature is appended to a message these directives set the From:Dand/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:

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

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

8
[user-options-override]\[smtp-from] !

N3.4 [html-editor-load]

C

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

A

So far it has been tried successfully with




8      
)

FCKeditor 2.2

¯

http://www.fckeditor.net/
http://sourceforge.net/projects/fckeditor/


8     
,

TinyMCE 2.0,3.0

ó

http://tinymce.moxiecode.com/
http://www.moxiecode.com/









A

Make your choice. Mine is TinyMCE. It does notErequired an ODS-5 volume. Install it independently of soyMAIL. Check>configuration requirements for the editor. Modify the soyMAILBconfiguration directives to provide the path to the editor and theEinitialization JavaScript code, both of which will be provided in the9editor installation guidelines, and voila! The functionsChtmlEditorContent() and htmlEditorLoad() must beHpresent (even if empty as in the case of TinyMCE), being an onload=Ctarget forthe document.

K

TinyMCEExample

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

>This would also require a server mapping rule into the TinyMCE?installation. For the above configuration and WASD it might besomething like

pass /tinymce/* /$1$disk/tinymce/*

)FCKeditor Example

3
[html-editor-load]f<script type="text/javascript" src="/FCKeditor/fckeditor.js"></script>/<script type="text/javascript">function htmlEditorContent() {@   var oFCKeditor = FCKeditorAPI.GetInstance('compose_text');\n\   return oFCKeditor.GetHTML();}function htmlEditorLoad(){3   var oFCKeditor = new FCKeditor('compose_text') ;2   oFCKeditor.BasePath = "/fckeditor/" ;!   oFCKeditor.ReplaceTextarea() ;}</script>

,Along with a similar mapping requirement

G
pass /fckeditor/* /$1$disk/fckeditor/*

F3.5 [logout-realm]

A

This configuration directive only applies whenAusing Web server authorization. It is not needed and is not usedDwhen using soyMAIL own authentication and state management (section>4). The following description only applies to Web server HTTPauthorization.

C

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

E

As described above this is a Kludge with a capitalFK. Why HTTP/1.1 didn't include a 418 (authorization canceled) –Eor some mechanism such as this – I'll never know! Not only are@there inconsistencies in the way browsers handle this (hence theCcredential 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 the5browser as an authorization refusal. So...

C

WASD handles all thiswith its usual panache :-)

E

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

;

For an Apacheconfiguration of

V
<Location ~ “^/cgi-bin/soymail/\~”>AuthType Basic+AuthName "OpenVMS authentication"AuthUserOpenVMS Onrequire valid-user</Location>

)the soyMAIL configuration must be set

G
[logout-realm]  OpenVMS authentication

For an OSU configuration of

R
protect /htbin/soymail/~* www_system:soymail.prot

'and a soymail.prot configuration of

:
<realm> VMS account*@*.*.*.* *

*the soyMAIL configuration would be set

<
[logout-realm]  VMS account

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

^

3.6 [private-access]

E

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

O

TheCprivate access URI must have been made subject to either Web serverDauthorization, or to soyMAIL autogenous authentication (section 4). BIf there is no browser username/password dialog, or no login page,2then it's not configured correctly!

B

soyMAIL identifies private access when the pathAhas the leading characters “/~”. For example, in thecase of Apache and WASD

3
/cgi-bin/soymail/~L

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

B

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

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

AThe realm allows WASD authentication realms to be factoredAinto the mappings but almost always will remain an asterisk.

B

If there is a one-to-one correspondence betweenCthe Web-server authenticated user name (as it is common to use someDform of SYSUAF-based authentication this is usually the case) then aDsimple rule against the directive is enough to allow any user access to Mail.

A
[private-access]  */*/*

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

1
[private-access]system/*/_systemanother/*/_another*/*/*

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

1
[private-access]freddo/*/nurkf	jd/*/doejV*/*/*

"Postmaster

E

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

:
/cgi-bin/soymail/~daniel/

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

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

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

|

3.7 [private-request]

E

By default the leading characters “/~”Cof the path indicates to@soyMAIL a private access request. This directive overrides thatBtilde sentinel and allows any request to be recognized for privateBaccess. It intended to be used inside a conditional configuration?test (section 3.12) based on some characteristic of the request reflected in a CGI variable.

E

The followingRexample shows a configuration test for the presence of a REMOTE_USERHvariable indicating it is a request subject to server authorization.

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

@This effectively directs soyMAIL to consider any such authorizedrequest is private access.







?

The secondAexample shows a test based on the request script name and assumes:that the server has mapped the path /mail onto the soyMAILexecutable.

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

EThe first leading caret indicates it is a regex pattern; the second aBregex 'beginning of line' symbol; then the string used to activateCsoyMAIL; and a regex 'end of line' dollar symbol. This makes it anexact match test.

E

Note that theC[private-request] directive must be specified before the use of any?directives that rely on recognition of private or@public access (e.g. [if-private], [if-public], [private-access],[public-access], etc). 

\

3.8 [public-access]

D

This facility is intended to allow general access?to a managed subset of a users Mail. Public access requires noDauthentication (though it is not forbidden either). There are threeDvariations on public access. The first rigidly controls access to aEspecific folder, in a specific mail file, in a specific VMS account. AThe second, a wildcard folder specification, allows access to anyAfolder in the specified mail file and account. The third, also a@wildcard specification, prohibits access to the account MAIL andNEWMAIL folders.

,

The general format is

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

"with the full wildcard variant

j
/<public-path>/ /<username>/<mail-file>/*/

8and the prohibited MAIL and NEWMAIL wildcard variant

k
/<public-path>/ /<username>/<mail-file>/*!/

BBoth wildcard variants allow an initial folder to be specified

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

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

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

$The first rule would map the URL

Q
http://the.host.name/cgi-bin/soymail/an_example/

Cto VMS account NURKF, the default mail file MAIL.MAI and the PUBLIC1folder in that. The second rule maps the URL

V
http://the.host.name/cgi-bin/soymail/another_example/

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

2

The third rule maps the URL

M
http://the.host.name/cgi-bin/soymail/public/

>to the LARRY account, mail file MAIL.MAI and an initial folderCMY_PUBLIC, with access allowed to all other folders except MAIL and NEWMAIL.

^

3.9 [search-control]

C

Mail message searching can be a very compute andDI/O intensive activity. Essentially soyMAIL searching is performed8on two levels with significantly different expenses.

D

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

C

The following parameters to the [search-control]Bdirective allow fine control of the extent of search capability toBassist in managing the system impact of this activity. ConditionalBconfiguration (see below) makes it possible to apply these to someBrequests and not others. One or more, space-separated, can be usedagainst the directive.

„                            


Parameter




Description




full


@

Is the default if [search-control] is not configured.




header-only


8

As described above this is quite lightweight.




keyword-only


E

Disable regular expression matching. It is still available to! configuration directives.


*

priority=<integer>


?

Once message body searching begins this moves the scriptB process priority to that specified (0..4) and restores it when searching completes.




none


@

Disables searching completely (and is obviously the least expensive :-)


e

3.10 [smtp-default-host]

A

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

C

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

E

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

e

3.11 [update-last-login]

B

For sites with a requirement to track continuedAaccount usage this directive results in the SYSUAF interactive orBnon-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 orCselection of a bookmark/favourite. Continued use of an established?session (using the buttons or new mail check facility) does not2result in updates to the last-login date/time.

D

Parameter to this directive should be INTERACTIVEor NON-INTERACTIVE.

q

#3.12 Conditional Configuration

A

soyMAIL has a useful facility allowing dynamicDconfiguration of soyMAIL processing based on request characteristicsEand CGI variable content. This allows a single configuration file to6support multiple site appearances or capabilities.

E

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

„                                


Directive




Description


'

[if-CGI-<name>]


C

If the CGI variable specified by <name> matches; the directive string then process the directives to the corresponding [if-end].


+

[if-not-CGI-<name>]


C

If the CGI variable specified by <name> doesE 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]


F

Terminates a block started by a matching [if-..] directive.




[end]


B

WARNING: Terminates all further configurationD processing at that point. This is intended merely to save a few? CPU cycles. Deploy inside relevant [if-..] directives.


K

KeywordExample

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

0Equivalent Regex Example

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

=Regex Equivalents of Common Wildcards



7                  
Y

asterisk ('*')


X

matches1 zero or more characters


W

period. then asterisk ('.*')


Y

question$ mark ('?')


X

matches. any single character


W

period ('.')


[

Percentage ('%')


X

matches. any single character


W

period ('.')









M

'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 theCfollowing test will be true. If the variable does not exist or has)an empty value then it will be false.

F
[if-CGI-<variable_name>]

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

J
[if-not-CGI-<variable_name>]=

9Conditional Configuration Example

F
# first directives for private access[if-private]age-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!6[public-access] /public-2005/ /WEBMASTER/MAIL/PUB2005/[if-end]

h3.13 Regular&Expression Overview

?

soyMAILDemploys the GNU RX1.5 regular expression package. Evaluation is done=using case-insensitive, EGREP-compatible matching. A detailedDtutorial on regular expression capabilities and usage is well beyondSthe scope of this document. This?summary is only to serve as a quick mnemonic.

@

Also see²http://en.wikipedia.org/wiki/regular_expression







a

soyMAILMregular expressions support the following set of operators.

L                                                


Description




Usage




Match-self Operator




Ordinary characters


$

Match-any-character Operator 



.


!

Concatenation Operator




Juxtaposition




Repetition Operators




* + ? {}




Alternation Operator



|




List Operators




[...] [^...]




Grouping Operators




(...)


"

Back-reference Operator




\digit




Anchoring Operators




^ $




Backslash Operator


5

Escape meta-character (e.g. \ ^ . $ | [ ()








E

The following;operators are used to match one, or in conjunction with theBrepetition operators more, characters of the target string. TheseCsingle and leading characters are reserved meta-characters and mustEbe 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








B

RepetitionAoperators control the extent, or number, of whatever the matchingDoperators match. These are also reserved meta-characters and must beWescaped using a leading backslash if required as a literal character.

L                                


Expression




Function



*



Match 0 or more times



+



Match 1 or more times



?



Match 1 or zero times




{n}



Match exactly n times




{n,}


!

Match at least n times




{n,m}


5

Match at least n but not more than m times








q

Checking,Regular Expressions

C

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

Ä
$ SOYMAIL /REGEX ”<text to be matched>” “<pattern>”





S4 Autogenous Authentication

K

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

H

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

H

The™client browser must support and have enabled HTTPTcookie;functionality. A cookie is used to store and propagate theaauthentication state. Thewcookie expires at the close of the browser. TheEcookie value is encrypted using the industry standard RC4 algorithm. BThis data is only present as plain values inside the processing of!soyMAIL.

L

soyMAIL'authentication

G

In)addition soyMAIL

H

The:internal authentication mechanism (site-specific, external­authentication is possible, see section 4.4)Adepends on the VMS platform and version.

L

FurtherLdiscussion will be confined to ACME authentication.

I

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

N

Technical?detail on the encryption algorithm, authentication code, cookieEstructure, etc., can be obtained from the descriptive prologue of the4LOGIN.C source code module.

^

d4.1 Configuration

G

IfAWeb server authorization for soyMAIL is currently configured thenDdisable this before proceeding further. Behaviour with both enabled*is indeterminate.

O

AutogenousCauthorization is enabled by configuring a value against the soyMAILAconfiguration directive [login-secret]. This is used as a key toEencrypt the soyMAIL credential cookie value. When this directive has9a value against it soyMAIL attempts to establish it's ownBauthentication state. As this is an encryption key care should be.taken to ensure it is

G

Anœexample/configuration might be

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

H4.2 Password$Change

m

soyMAILDauthentication will detect an expired password for DIALUP, LOCAL andAREMOTE login types. ACME does report expiration for NETWORK (theDdefault). An expired password will fail unless [login-no-pwdexp] isAENABLED or soyMAIL password change is configured and the password9must be changed at login.

n

PasswordAchange is enabled by specifying the location of the change dialogíHTML (also see section 4.6).E Using the default file that would be

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

UAsDwith authentication password change is either performed by ACME or aBsoyMAIL code path. The latter is rudimentary and does not includeCsuch desirable facets as dictionary and password history checking. ?Platforms without ACME available should avoid enabling password'change.

i

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




8              
U

[login-type] 3

K

LOCAL

U

[login-type] 4

L

DIALUP

U

[login-type] 5

L

REMOTE



7





V

b4.3 Login Alias

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

@

The format is oneDalias mapping per line, with the supplied user name to be matched on?the left, a forward-slash, and the username to be authenticatedagainst on the right.

.
[login-alias]Mark.Daniel/DANIELFred.Bloggs/BLOGGS

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

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

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

C

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

.

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

x

A4.4 External2Authentication Agent

j

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


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

[Optionalbparameters can be provided as part of the configuration directive:

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

WWhenBactivated the procedure has a further three parameters appended toPany supplied in the above configuration directive; "<username>",D"<password>" and "<remote_addr>", toIbe used in the authentication processing.

i

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







D

This is a (verysimple) example.

$ SET ON|$ OK = 1$ NOPRIV = 36˜$ P1 = F$EDIT(P1,"UPCASE")Â$ IF P1 .EQS. "CURLY" .AND. P2 .EQS. "JeromE" THEN EXIT OKÁ$ IF P1 .EQS. "LARRY" .AND. P2 .EQS. "lOUIs" THEN EXIT OK¿$ IF P1 .EQS. "MOE" .AND. P2 .EQS. "harrY" THEN EXIT OK$ EXIT NOPRIVžThis would probably be more like a working one.|$ SET ON¡$ SOYAUTH = "$location:SOYAUTH.EXE"³$ SOYAUTH "''P1'" "''P2'" "''P3'"$ EXIT $STATUS

4.5 LOGIN.HTML

i

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

h

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

Ö
[login-page]  SOYMAIL_THEME:_LOGIN.HTML

X4.6 CHANGE.HTML

A

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

C

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

Þ
[login-change-page]  SOYMAIL_THEME:_CHANGE.HTML

84.7 Access Log

C

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

E

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

[access-log]  HT_LOGS:SOYMAIL.LOG

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

»
[access-log]  HT_LOGS:SOYMAIL_%04d.LOG4

DIn a similar fashion, toAinclude the month add a second numeric formatting string, and theUday-of-month a third, as illustrated in the following two examples.


ž[access-log]  HT_LOGS:SOYMAIL_%04d%02d.LOG¢[access-log]  HT_LOGS:SOYMAIL_%04d%02d%02d.LOG

DsoyMAIL enables SYSPRV toCaccess the file and so it may be located in a protected area of thefile-system.

E

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

\

5 Customization

:

soyMAIL provides three levels ofcustomization.

D

5.1 Locale

E

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

A

If you wish to put a language-specific messageDfile together for soyMAIL please contribute it back into the soyMAILDcommunity. Note that messages can be used in all sorts of contexts,Dparticularly inside string literal quotes - both single and double. EIt is therefore necessary to substitute the HTML entities &quot;,?&rsquo;, etc., for anything that might be misinterpreted asEJavaScript code quotes (i.e. " (0x22) and ' (0x27)). If soyMAIL>reports a message file fatal error the SOYMAIL$WATCH facilityG(section 7.1) can be used to help determine the underlying problem.

E

The [.HELP] directory contains the default EnglishBlanguage, on-line, content-sensitive help files. These contain the=help information and HTML markup. Each files name contains an>indication of the language, where the English version might beBHELP_EN.HTML, the French language version HELP_FR.HTML, etc. TheseBfiles are dynamically accessed and composed by soyMAIL when a userCaccesses on-line help. The users language option is used to searchEfor a possible file with that language indicated in the name. If not?found it supplies the default English language version. One orC(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 soyMAILcommunity.

@

5.2 Site

=

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

D

The SMTP host and apparent source of messages canbe specified.

A

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

I

LocalUser Option Defaults

E

Users options may be defaulted and overridden.

C

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

7
[user-options-default]\[language]  de

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

8
[user-options-override]?\[theme] _draco_corp

DThe user option to specify a “From:” address line can bedisabled with

8
[user-options-override]9\[SMTP-from] !

Two notes:

I

LocalHelp

?

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

U

5.3 User

?

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

@

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







L                  
M

Directive


O

Description


U

[accessability-1]


A

enables a heavy7 underscore beneath each line of the message listing - (accessability [sic] :-)


^

[message-attachment-panel]


E

0 below the message' (default), 1 above


Z

[options-panel-expand]


@

0 user optionsE panels 'just wide enough', 1 panels 100% of main panel (Wm(B)K$ special :-)








a

6 soyMAIL User Files

E

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

L                                    


File Name




Purpose


'

SOYMAIL_nnnnnnnnnnnnnnnn.ATT


D

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


E

Plain text file containing the soyMAIL-specific signature.


"

SOYMAIL_SIGNATURE_*.TXT


.

User-created signatures (as above).


!

SOYMAIL_YOUGOTMAIL.WAV


D

Binary audio file containing users optional “you've got" mail” audible alert.








M

ExtractedFiles

E

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

M                                        


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 bytes




none








c

7 Miscellaneous Topics

G

Miscellaneous soyMAIL features and other topics.

!7.1 Run-time Problem Solving

D

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

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

<Please include this information when reporting problems.

9

Defining the system-level logical nameBSOYMAIL$WATCH to either TRUE or the IP address of the client to beCobserved provides a plain-text report designed to assist in solving2configuration or software issues with soyMAIL.

F

7.2 Inconsistent State Data

>

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

>
  Inconsistent state data (version).  Restarting session.

CThis is of no concern. The change in version has been noted by the=software and to prevent any potential inconsistencies in dataDstructures causing subtle or gross problems it has reinitialized the?state data resulting in an effectively empty session. The userGshould just reopen (not refresh/reload) the particular page.

C

The second variation of this message is a littlemore concerning.

A
  Inconsistent state data (corruption).  Restarting session.

CsoyMAIL maintains a hash of the state data which is propagated withEit. The hash is recalculated and compared at the next request. ThisDerror reports the comparison failed and indicates data corruption in;the request state. The session is effectively emptied as aEprecautionary measure. Instances of this message should be very rare-and if persistent carefully investigated.

K

%7.3 Site Contact / Mailing Lists

D

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

E

For example:

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

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


  ALL_USERS_LIST  GROUP1_USERS_LIST  GROUP2_USERS_LIST  GROUP3_USERS_LIST  EXTERNAL_LIST

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

H

LDIFAddress Lists

=

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

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

?This purges all but:soyMAIL relevant elements from the data.

P

7.4 GeneralAccess To Help

9

Context-sensitive help is available toAauthenticated users accessing private mail. A page built from theIconsolidated help information (and distinctly resembling the printApage for context-sensitive help) is available for unauthenticatedA(general) access. Use the following URL to access this page.

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