yahMAIL Usage Guide

6 - Configuration

6.1 - Installation
6.2 - Non-English and Multi-Language Support
6.3 - Authorization
6.4 - Access and Environment
    6.4.1 - Public Access
    6.4.2 - Private Access
    6.4.3 - Page Presentation
    6.4.4 - Configuration File Example
6.5 - Archive Customisation
[next] [previous] [contents] [full-page]

This version of yahMAIL is known to function with

Configuration comprises three main aspects. 

  1. installation
  2. user authentication and authorization
  3. yahMAIL access and environment

All of these are covered here from the perspective of the WASD server package.  The yahMAIL facility is designed with compatibility with OSU and vanilla-CGI environments in mind, so configuration specifics mentioned here-in should have the principles applied to non-WASD environments. 


6.1 - Installation

Be aware that anyone who can modify scripts within the HTTP server's file space, or otherwise change server configuration, potentially can affect yahMAIL's behaviour. 

Summary of files required for operation:


6.2 - Non-English and Multi-Language Support

Support for non-English language text, buttons, messages, etc., is provided through separate object modules containing the strings for these.  These may be compiled/linked into the script.  In addition it is a straight-forward matter to create a new version.  Simply copy the source of the English language version to a new file, translate the required messages, compile, link and install.  Full instructions may be found in LANG_EN.C in the source code directory, along with any other languages previously translated and provided to the author. 

Multi-language versions of yahMAIL on a single site can also be supported.  The general approach is to rename any language-specific executable (and it's support procedure) from the default YAHMAIL.EXE to YAHMAIL_language.EXE, allowing users to select their language of choice using URLs as in the following examples. 

  http://server.host.name/cgi-bin/yahmail_en/~
  http://server.host.name/cgi-bin/yahmail_de/~
  http://server.host.name/cgi-bin/yahmail_se/~

Of course, startup procedures and authorization environments would also need to be adjusted to accomodate such an extended environment. 


6.3 - Authorization

If yahMAIL is to be used for authenticated access (i.e. individual VMS users to their own, private email) then it becomes the server's responsibility to authenticate and authorize these names.  The script checks for the CGI variable "WWW_REMOTE_USER" and uses this as an authorized username.  When non-empty this variable indicates that private rather than public access is being sought.  When empty, that public, essentially archive access. 

To use yahMAIL for both archive and private access some means of differentiating the two to the server is required.  This is attained by having the private access path always begin with a particular character, the tilde ("~"). That is, have the server require authentication if the following is requested

  http://server.host.name/cgi-bin/yahmail/~
but not if this is requested
  http://server.host.name/cgi-bin/yahmail/archive-name


WASD Example

For WASD this requires an HTTPD$AUTH mapping such as the following:

  [realm-name]
  /cgi-bin/yahmail/~* r+w


OSU Example

For OSU a protect rule must be used to trigger authorization:

  protect /htbin/yahmail/~* www_system:yahmail.prot

or if using the configuration script pages something like:

  .ITERATE $xrule $xtemplate $xpath
  .NEXT protect /htbin/yahmail/~* /www_system/yahmail.prot

with the [.WWW_SYSTEM]YAHMAIL.PROT containing the required authenticator access control directive(s). 


Apache Example

There are a number of ways of configuring authentication and authorization using Apache.  This example shows [CONF]HTTPD.CONF entries for the use of the SYSUAF. 

  # YAHMAIL.CONF will need to have it's paths to the documentation edited!
  Alias /yahmail/doc/ "/apache$common/src/yahmail/doc/"
  
  LoadModule auth_openvms_module
  /apache$common/modules/mod_auth_openvms.exe_alpha
 
  <Location /cgi-bin/yahmail>
  AuthType Basic
  AuthName "OpenVMS authentication"
  AuthUserOpenVMS On
  require valid-user
  </Location>
Simple Test

If the browser is not (at least initially) prompting for a username/password before allowing access to /cgi-bin/yahmail/~ then the Web server's authorization is not set up correctly! 

For reasons discussed in 7.8 - Security it might be appropriate policy to restrict authenticated access to yahMAIL to SSL secured transactions.  For WASD this can be done using,

  /cgi-bin/yahmail/~* https:,r+w

Note that the use of the tilde ("~") in this manner may interact with the authorization of any user paths that begin with a tilde (due to WASD's authorization of both script and path portions in a request).  If this is the case then choose any other non-alpha-numeric character to introduce the username portion of the path.  yahMAIL detects this first character and configures itself to use this for the request.  Reasonable options are the period ("."), dollar ("$"), circumflex ("^"), underscore ("_") and hyphen ("-"). These would result in URLs similar to the following:

  http://server.host.name/cgi-bin/yahmail/.
  http://server.host.name/cgi-bin/yahmail/$
  http://server.host.name/cgi-bin/yahmail/^
  http://server.host.name/cgi-bin/yahmail/_
  http://server.host.name/cgi-bin/yahmail/-
NOTE

The authentication realm (i.e. source of username/password verification) does not need to be the system's SYSUAF database.  It can be any source supported by the server.  The yahMAIL configuration file allows a mapping to be made between the authenticated name and the actual VMS username used for mail access. 


6.4 - Access and Environment

This section basically covers the modifications required to the yahMAIL configuration file to control access to public archives, private VMS email, operational aspects of the script, and the presentation of responses to requests (e.g. page headers and footers). 

Once the facility has been started the configuration may be altered at any time by editing the file YAHMAIL$CONFIG and saving the modifications.  This file is read at the beginning of processing with each request.  If this file does not exist or cannot be accessed for any other reason all requests will be denied access with a message stating "configuration restriction".  No further detail is provided quite deliberately to reduce leakage of any potentially sensitive site information. 

The configuration file is divided into sections delimited by square-bracket directives.  They must begin on the left-most boundary of a line.  No square-bracket other than a directive may occur in that position.  Text associated with that directive continues until the next directive or end-of-file.  Directive text may span lines as appropriate.  Leading and trailing white-space is trimmed and ignored. 


Access Checking

To assist with initial configuration and any subsequent access problems a report on configuration access processing can be requested via the definition of a logical name. 

  $ DEFINE /SYSTEM YAHMAIL$CHECK 1

When this logical exists access to yahMAIL is disabled and requests to it have a message returned stating this.  In HTML comments following the message (look at the source of the page) is a record of access processing.  This contains the reasons for and results of any access decision. 


Disabling Access

Should there be need to disable all access to yahMAIL for any reason the following logical name will result in requests receiving an informational message and no access. 

  $ DEFINE /SYSTEM YAHMAIL$DISABLE 1


6.4.1 - Public Access

Public access is provided to archives specified by Mail file location.  No username is, or needs to be, associated with this specification.  Browsing of the entire file's contents is possible, or access may be restricted to one or more folders only.  Each archive is configured with a single line entry in the [public] section.  The format has three sections separated by back-slashes. 

  archive-name \ Mail file specification \ optional restricting folder name

In the following example the first and second lines would provide access to all folders in the files WEB:[ARCHIVE]MAIL_1997.MAI and WEB:[ARCHIVE]MAIL_1998.MAI respectively, the third line to the recent folder only in file USER_DISK:[WEBMASTER]MAIL.MAI, and the fourth and last to the public folder in USER_DISK:[FRED]MAIL.MAI file.  Note that there is no correspondence necessary between any of the strings in the three sections. 

  [public]
  web-1997\WEB:[ARCHIVE]MAIL_1997.MAI\*
  web-1998\WEB:[ARCHIVE]MAIL_1998.MAI\*
  web-recent\USER_DISK:[WEBMASTER]MAIL.MAI\recent
  fred-public\USER_DISK:[FRED]MAIL.MAI\public

Respectively, each of these could then be accessed by the following requests. 

  http://server.host.name/cgi-bin/yahmail/web-1997
  http://server.host.name/cgi-bin/yahmail/web-1998
  http://server.host.name/cgi-bin/yahmail/web-recent
  http://server.host.name/cgi-bin/yahmail/fred-public

Note that the following requests would also be allowed,

  http://server.host.name/cgi-bin/yahmail/web-1997/december
  http://server.host.name/cgi-bin/yahmail/web-1998/january
  http://server.host.name/cgi-bin/yahmail/web-recent/recent
  http://server.host.name/cgi-bin/yahmail/fred-public/public

but these forbidden. 

  http://server.host.name/cgi-bin/yahmail/web-recent/NEWMAIL
  http://server.host.name/cgi-bin/yahmail/web-recent/anything-else
  http://server.host.name/cgi-bin/yahmail/fred-public/MAIL
  http://server.host.name/cgi-bin/yahmail/fred-public/like_wise


6.4.2 - Private Access

Access to private VMS mail areas is not possible without HTTP server authentication and authorization.  The yahMAIL configuration does not authorize access, it merely maps from the authorized username to a VMS username, which is then used for as the basis for access (the differentiation of which is not just pedantic :^)

Hence, the authorization environment does not need to be based on the system's SYSUAF database.  It can be sourced from whatever is available to the server and in use on any particular site.  Of course, it can be based on authentication via the SYSUAF, in which case there is a one-to-one correspondence between the authentication and VMS Mail username.  If not based on system authorization then there either can be a direct relationship between authenticated username and VMS Mail username ... or not.  It doesn't affect the ability to use the facility, just the number of mapping entries required. 

In either case access to Web-based VMS mail may be allowed or restricted on a per-username basis and so allows for great flexibility.  Each is configured with a single line entry in the [private] section.  The format has three sections separated by back-slashes. 

  authenticated username \ authentication realm \ VMS mail username

The authenticated username is the string found in the "WWW_REMOTE_USER" CGI variable.  The authentication realm is a WASD-specific CGI variable "WWW_AUTH_REALM", providing the database name from which the username was authenticated.  For non-WASD installations this should be replaced with a wildcard asterisk ("*") representing any or no realm.  The VMS mail username is the username actually used for access to Mail. 

The following example shows three users being provided with mappings to VMS user names after authentication from the "web-access" source.  All other are explicitly denied access by mapping to a non-alphabetic VMS user name. 

  [private]
  moe\web-access\HORWITZM
  larry\web-access\FINEL
  curly\web-access\HORWITZJ
  *\*\-

If the authenticated username corresponds directly with the VMS username then a wildcard asterisk may be substituted.  This example provides essentially the same configuration as the example above (assuming a sinlge authentication source). 

  [private]
  HORWITZM\*\*
  FINEL\*\*
  HORWITZJ\*\*
  *\*\-

A special case is if authentication is being done against the system's SYSUAF and all users are allowed access.  This essentially maps any authenticated username to the same VMS username. 

  [private]
  *\*\*

Of course it's still possible to selectively prevent access to some accounts. 

  [private]
  SYSTEM\*\-
  DECNET\*\-
  BLAH\*\-
  *\*\*

Remember that multiple username/password environment can be verified by cancelling a current authorization and initiating a new one as described in 3 - Authenticated User Guide


POSTMASTER

The POSTMASTER, for obvious reasons, must be an authenticated user.  Designation of a username as a POSTMASTER is quite simple.  Instead of a VMS Mail equivalence name use "postmaster" instead.  Zero, one or multiple such POSTMASTERs may be designated.  Use with caution.  Here is an example showing two of all authenticatable users from the VMS source being able to act with POSTMASTER access. 

  [private]
  daniel\VMS\postmaster
  defoe\VMS\postmaster
  *\VMS\*

As an additional safeguard on this very powerful facility the yahMAIL qualifier /POSTMASTER is required to be applied before anyone can be mapped to be a POSTMASTER.  This can be added to the YAHMAIL.COM script support procedure or defined in a system-level logical YAHMAIL$PARAM. 


CAUTION!!

Care should be exercised with the configuration file.  Misconfiguration could conceivably leave the mail system open to inappropriate access.  For instance, mapping an authenticated name to the wrong VMS username.  The code has been designed to minimise the risk of catastrophic errors, for instance mapping all authenticated users as POSTMASTERs.  Also, unless a username is explicitly mapped in some way it will be rejected.  But, do not map all authenticated users to VMS usernames unless the source of the authentication is the SYSUAF, or unless the realm usernames always correspond the appropriate VMS username.  That is, do not do something like

  *\not-from-SYSUAF\*

For the same reasons do not map all realms with a wildcard unless you have only the one authentication realm, from the SYSUAF, or all realm names are authenticated from the SYSUAF, or all usernames in the realm correspond to the appropriate VMS usernames.  That is, do not do

  *\*\*


6.4.3 - Page Presentation

Various aspects of yahMAIL behaviour and page generation may be controlled using configuration file directives.  Note these directives must precede those related to private and public access control.  To reiterate, the [public] and [private] directives must be the last in the file! 


6.4.4 - Configuration File Example

This example attempts to illustrate what a YAHMAIL$CONFIG file might look like with various options and access controls configured. 

  [#] example YAHMAIL configuration file
  [body]
  BGCOLOR="#ffffff" TEXT="#000000" LINK="#0000ff" VLINK="#000000ff"
 
  [createfooter]
  <A TARGET="yahMAILhelp"
  HREF="/ht_root/src/yahmail/doc/guide_create.html">Create-Send Guide</A>
 
  [folderheader]
  <FONT COLOR="#ff0000">
  Unauthorized access via <B>yahMAIL</B> is prohibited!<P>
  </FONT>
 
  [folderfooter]
  <A TARGET="yahMAILhelp"
  HREF="/ht_root/src/yahmail/doc/guide_folder.html">Folder Browse Guide</A>
  Site <A HREF="/web/">Home Page</A>
  <BR>Mail <A TARGET="yahMAILhelp" HREF="/web/archive/">Archive Policy</A>
  <BR><A TARGET="yahMAILhelp"
  HREF="/ht_root/src/yahmail/doc/">yahMAIL Usage Guide</A>
 
  [listfooter]
  <A TARGET="yahMAILhelp"
  HREF="/ht_root/src/yahmail/doc/guide_lists.html">Address List Guide</A>
 
  [readfooter]
  <A TARGET="yahMAILhelp"
  HREF="/ht_root/src/yahmail/doc/guide_read.html">Message Read Guide</A>
 
  [#] let's pretend this is a pre-VMS6.2 system and specify an SMTP transport
  [smtp] MX%
 
  [list]
  all_users USER_DISK:[LISTS]ALL_USERS.DIS
  webmasters USER_DISK:[LISTS]WEBMASTERS.DIS
 
  [private]
  system\wasd_vms_rw\postmaster
  daniel\wasd_vms_rw\postmaster
  *\wasd_vms_rw\*
 
  [public]
  web-1997\WEB:[ARCHIVE]MAIL_1997.MAI\*
  web-1998\WEB:[ARCHIVE]MAIL_1998.MAI\*
  web-recent\USER_DISK:[WEBMASTER]MAIL.MAI\recent
  fred-public\USER_DISK:[FRED]MAIL.MAI\public


6.5 - Archive Customisation

A public folder browse page may be customised by adding a special message to a folder.  This message is identified by having the subject field contain "!yahMAIL! " (case sensitive).  It is searched for prior to generating a public page and if found the contents override configuration file equivalents.  It is generated by mailing a message with this subject keyword and the body containing the directives described below to the required account and then moving it to the desired folder if required.  The most recent of such messages will be used (but delete any previous ones as good maintenance practice). 

The message body works in much the same way as the yahMAIL configuration file (see 6.4.3 - Page Presentation), with keywords delimiting free-form text directive contents. 


[next] [previous] [contents] [full-page]