Mailcorral Documentation

4. User Support

MailCorral provides virus and spam filtering at the system level for all mail delivered by sendmail. While some filtering options may be applicable to all email delivered, many users may prefer to set certain options according to their individual tastes. MailCorral allows users to tailor how it filters their mail via individual config files or a configuration database.

4.1 Configuration Methods

Individual configuration file support allows a user to create a config file in their home directory ("~/.sendmailfilter", by default, unless "smfopts.h" is changed prior to compiling the filter) where all of the local options may be specified. These local options are applied to each message, based on the recipient of the message. When a message is received, the recipient's username is determined and then their local options file is looked up and processed to arrive at the options used to filter the message.

In many instances, MailCorral is employed by organizations that have a large number of users (e.g. ISPs) but where the users are essentially virtual users. That is to say, the users don't have traditional accounts in the sense that they have home directories or other accoutrements normally associated with real users. More importantly from our point of view, they have no place to conveniently store a user options file.

If your system has virtual users, individual user support is still possible through MailCorral's DBM database configuration file. Using this option, all of the user settable parameters are stored in a single configuration database, which may be located anywhere. The virtual user's name is used to store and lookup the parameters and everything else works as if they were a real user. This feature is enabled via the "-c" command line option or the "ConfigDB" config file parameter.

Note that, when you are using virtual user support, you might also want to use fully qualified names for storing configuration information in the configuration database. Since it is possible for the same username to exist in two domains (e.g. "custserv"), domain information must be used to qualify the username and ensure that the name used to store configuration information is unique. This is done by specifying the "-q" command line parameter or "QualifyNames" in the global configuration file.

In the case of the individual configuration file, the user may utilize a text editor to edit the parameters within it. However, in the case of the DBM database, this isn't possible. Either way, a nice user interface, that allows a user to easily edit their configuration options, would be better.

The purpose of MailCorral's configuration editor ("ConfigEdit.cgi") is to provide individual users with a simple, easy to use method of editing configuration parameters. It is a Perl program that runs as a CGI script under a Web server. The user visits a configuration form, with their Web browser, where they see all of their configuration parameters and where they can edit them. Once they have made changes to the form, the results are posted back to the same CGI script which then updates the local config file or DBM database.

The configuration editor is actually a generic config file and/or DBM database editor that is driven by an HTML template file. It can be set up to edit one or more config files and/or DBM databases in a single form. The form, since it is governed by an HTML template, can be tailored to have whatever look and feel a site desires, probably that of their standard configuration pages.

A sample HTML template file ("MCEdit.html") is shipped with MailCorral that implements a simple form with all of the configuration parameters that a user would want to edit. This form defaults to edit "~/.sendmailfilter". A comment immediately after this file name, in the template, shows how to edit the DBM database "/etc/mail/MCUsers". You can use the template pretty much as is or alter it to get something more to your liking.

Note to RPM installers. The configuration editor and sample template are installed in the "/etc/mail" directory, for want of a better place to put them, not knowing how you have your Web server set up or even if one exists at all. You can link to them there or move them to wherever else you want.

4.2 Configuration Editor

The configuration editor ("ConfigEdit.cgi") should be moved to the appropriate CGI directory for your Web server and given execute permissions, etc. You may have to alter the path to your Perl interpreter in the first line of the script. The editor is invoked by placing a link to it in a HTML document. The URL of the template to be loaded (minus the address of the server) is given by the "TplURL" parameter. Hence, the link should look something like:

You can debug this program and your templates by adding a value of "Debug" to the URL. For example:

The purpose of the template is to describe a form which displays and allows the user to edit the configuration values in a Unix-style configuration file. This program is also reinvoked by the form in the template to process the edits to the form data and update the configuration file. This reinvocation of the program should look like:

Any parameters that are to be replaced in the template are given by names which must exactly match the parameter names found in the config file. You can have as many parameters as necessary. Parameters will be replaced by blocks of HTML so, if you want the output to look presentable, each parameter should occur on a line by itself.

In addition to the HTML necessary to display the parameters, the template file must also contain three special comment blocks which describe how the parameter replacements should be done. These can appear anywhere in the template and will be removed before transmission.

The first block, named "configfile", simply gives the name of the config file who's parameters are to be displayed. Multiple config file names can be supplied, separated from each other by commas, in which case the field types (see below) need to be qualified with a number, indicating which config file the field comes from (the default, if omitted, is 1, the first config file).

All of the usual pathname expansion features are available. If the path begins with "~/", the parameter UserName must be supplied as one of the values when the script is invoked and this user name will be used to look up the home directory for the user. For example:

requires

Note that there is a potential security hole caused by this feature. A malicious person could cause a parameter file for a particular user to be updated by figuring out which parameters to pass to this program. As such, the program should be put in a password protected directory where it can only be executed by legitimate users who have previously supplied the correct password to the Web server.

Also note that, in order for the form to be able to recall this script with the user name needed to update the config file, the "$ConfigEditUserName$" parameter in the template file will be updated with the username passed on the command line. Although this precludes having a parameter in the config file with this name, it does allow the username to be passed along from invocation to invocation. You should probably use this feature as follows:

Finally, if you want to be able to access user files from Apache and to be able to create user files with the correct mode and permissions, you will need to run this script as setuid root. This shouldn't pose a problem because the only I/O that is done is to the config file, which is specified in the HTML template, although it is possible to supply a username and have a file created in that user's directories, wherever the template says it should be put. Consequently, I reiterate that this program should be put in a password protected directory where it can only be executed by legitimate users who have previously supplied the correct password to the Web server.

An alternate form of the user config file is allowed to support DBM-based user config files. If the file name starts with a pair of slashes (i.e. "//"), it is assumed to be a DBM database which contains the parameters as key/value pairs. In this case, the parameter UserName must also be supplied as one of the values when the script is invoked and this user name will be used to create unique keys for each user. For example:

requires

All of the discussion above, about the updating of the $ConfigEditUserName$ parameter, security and permissions applies equally to this database. The keys in the database will have their names composed of "username|parmname" while parameters that can have multiple values will have a numeric counter added to their keys to make them unique.

The second template comment block, named "fieldnames" is a list of field names plus information about them. Each field name must appear on a line by itself. The line contains the name, a type (including an optional config file index), a template name plus some additional information. The field types can be "btn" (button), "chk" (checkbox), "txt" (text) or "rpt" (repeating text). If the optional config file index is supplied (when the "configfile" section names more than one config file), it follows the field type immediately with no spaces in between (e.g. "chk2"). For each of the field types, here's how their entry in the template file must look:

The templates referred to above are small chunks of HTML that describe how to display the parameter as a field in the Web page (presumably a form). The fieldnames must match the parameter names in the config file. If a field takes values, they follow the template names.

The values given for each field are the default values, set before the config file is read. In the case of the checkbox, the unchecked value is set as the default value of the field but, when the substitution is made into the template, if the value being substituted matches the checked value, that value is substituted into the template followed by the tag "checked". Regardless of which value the parameter is set to, the checked value is always substituted with the only difference being whether the "checked" tag is added or not. Repeating fields have no default value but a single, extra, empty field will be created to allow for additions. The second template in a repeating field is used to provide a delete checkbox. The checkbox is left off for the generated, empty field.

The third special comment block, named "fieldtemplates" must contain the named field templates referred to in the first comment block. These also must occur one per line and look like:

tpltname|replacment HTML

In each template, the name of the field (i.e. the parameter name) replaces any occurrences of "@@" and the values replace any occurrences of "%%" and/or "^^", in the order in which they are seen and in the order of the values. The "@@" are substituted first. Then the "%%" are substituted next. Finally the list of values is re-substituted to replace the "^^", if any, mainly for the purpose of labeling radio buttons.

The HTML template that is given will be read and searched for all occurrences of the parameters in the config file that match field names in the fieldnames section of the template. These parameters must be surrounded by two dollar signs in the template (e.g. "$ParmName$") and must match the parameter names found in the config file exactly (except for case insensitive). Each occurrence of a parameter will be replaced in situ by its field template, after substitutions are made. Here is an example:


      <html>
      <head>
      <!-- configfile ~/.sendmailfilter,~/.otherparms -->
      <!-- fieldtemplates
      Button1|<input type=radio name=@@ value=%%> ^^ \
              <br><input type=radio name=@@ value=%%> ^^ \
              <br><input type=radio name=@@ value=%%> ^^
      Button2|<input type=radio name=@@ value=%%> ^^ \
              <input type=radio name=@@ value=%%> ^^
      Check1|<input type=checkbox name=@@ value=%%>
      Text1|<input type=text name=@@ value=%% size=20 maxlength=50>
      Delete1|  <input type=checkbox name=@@ value=%%>
      -->
      <!-- fieldnames
      ParmBtn1|btn|Button1|Top|Middle|Bottom
      ParmBtn2|btn|Button1|Fast|Normal|Slow
      ParmBtn3|btn|Button2|High|Low
      ParmCheck|chk|Check1|No|Yes
      ParmText|txt|Text1|Some text
      ParmList|rpt|Text1|Delete1
      OParmTxt|txt2|Text1|Other text
      OParmChk|chk2|Check1|Maybe Not|Maybe
      -->
      </head>
      <body>
      <form name="Config" action="cgi-bin/ConfigEdit.cgi?\
              UserName=$ConfigEditUserName$&\
              TplURL=MCEdit.html" method="post">
      <table align=left cols=2 cellpadding=0 cellspacing=0 border=0>
      <tr><td width=300>
      ParmBtn1 - The button 1 parameter ...
      </td><td>
      $ParmBtn1$
      </td></tr>
           .
           .
           .
      </table>
      <hr>
      <table align=left cols=2 cellpadding=0 cellspacing=0 border=0>
      <tr><td width=300>
      OParmTxt - The other config file text 1 parameter ...
      </td><td>
      $OParmTxt$
      </td></tr>
           .
           .
           .
      </table></form>
      </body></html>

The config file itself follows the normal rules for Unix-style config files. However, for the sake of making this program simpler, the updates are only done to the tail end of the config file. Also for the sake of simplicity, the parameter names must not end with one or more numbers nor include the string "__delete__" in them.

Only the parameters named in the "fieldnames" section of the template file are written to the form and updated in the config file. All other parameters are ignored. If you are smart, you'll put the parameters that are to be ignored at the start of the file and those that are to be updated at the end. This program makes no attempt to preserve the order of comments or the insertion order of updated parameters. Comments on the same lines as updated parameters are lost.

4.3 Web Page Template

The sample HTML template file ("MCEdit.html") should be copied to the appropriate HTML directory for your Web server. As supplied, the template implements a simple form with all of the configuration parameters that a user would want to edit. This form defaults to edit "~/.sendmailfilter". A comment immediately after this file name, in the template, shows how to edit the DBM database "/etc/mail/MCUsers".

Since the template is editing a config file that needs a user name to locate it, you will need to invoke the configuration editor with the "UserName" parameter. Probably the easiest way to do this is to create a simple, top-level form that contains a single text field which asks for the user's name. The submit button of the form should invoke the editor as follows:

Such a simple form might look like:


      <form name="User" action="/cgi-bin/ConfigEdit.cgi" method="get">
        <input type="hidden" name="TplURL" value="TplURL=MCEdit.html">
        <input type=text name="UserName" value="" size=20 maxlength=32>
      </form>

The configuration parameters that can be updated by the sample template are: AddXTags; AutoRemail; SpamAlways; SpamDel; SpamFast; SpamLevel; blacklist_from; and whitelist_from. Each of these parameters can be found documented in the Configuration section.

The parameters SpamDel and SpamLevel are implemented as radio buttons, in this case with three values, via the field template "Button1". The three values that follow the field name (e.g. "Corral", "Deliver" and "Trash") correspond to the three buttons in the field template. As an example, the first button in the field template for the SpamDel button would get expanded to read:

<input type=radio name=SpamDel value="Corral"> Corral

A second radio button field template, Button2, is included in the sample template as an example but it isn't used. It would be used for a parameter that had four values, like the DebugLev global parameter (it is possible to have a form that edits the global parameters too). You can leave it there (its harmless) or remove it, if you want.

The AutoRemail, SpamAlways and SpamFast parameters are implemented as checkboxes, via the Check1 field template. Note that the first value following the field template name, in the field, is the value that is chosen when the box is checked, while the second value is the unchecked value. In the sample template file, the operation of SpamFast is backwards, with "No" being the value chosen when the box is checked.

The AddXTags, blacklist_from and whitelist_from parameters are all text fields with identical characteristics, implemented by the field template Text1. The AddXTags field has no default value so it will appear empty when the form is brought up, unless the config file has some setting for it.

The blacklist_from and whitelist_from parameters, in addition to being text fields, are repeating fields. That means that they can have multiple values in the config file or database and that each value will result in a separate field in the generated form. On top of this, the Delete1 field template will be added to each occurrence of the text field, except the last one, which will be given an empty value. This allows additions of new values and updates or deletions of existing values.

The actual form itself is contained in a table with two columns. On the left is a paragraph explaining what each option is. On the right is the form field where the parameter value can by typed in, the checkbox checked or the radio buttons clicked. The repeating fields have two items on the right, a text field and a checkbox. There is a column heading above them so that the user can tell what's what.

If you would like to view the form, click here.

Note that the Language parameter was not included in the sample template file, since most installations of MailCorral will not require language support. If you should require it, add a multi-button radio field that has the languages you need and create a set of language configuration files in a convenient directory. Set the values of the radio buttons to the names of the language configuration files and you should be in business.