domail is a cgi program designed for use as a generic www email processor. domail was written to fill the need of several users on various virtual domains on a web server who needed a single, easy to configure script that they could use for their forms without the need to consult an admin or programmer. A single hidden field supplies the name of the configuration file to use, and the rest of the configuration for that form is derived from that file.

Written in perl, it should perform equally well on any un*x or windoze platform with a reasonably recent perl installation and a copy of the CGI module by Lincoln Stein (if not installed, it is available on CPAN).domail also requires a mail transport agent such as sendmail to deliver the mail. Other MTA's can be used if the script is slightly modified to accommodate their command line syntax.

domail incorporates some anti-spam and anti-spoofing measures. More testing is required to determine whether they are stringent enough to meet the demands of today's UCE-laden internet. However, they have proven sufficient on the number of domains where the script, and its predessors from whom its code is derived, are deployed.

Copyright (c) 2002, Dave W. Capella All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Dave Capella nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

1. Relies on Lincoln Stein's venerable CGI.pm module.
2. Restricts use to list of servers spelled out in script
3. No html is output in any event. on success or failure, redirects to pages specified in the configuration file.
4. Data is sent in an email to the address specified in the configuration file, one line at a time.
5. The order of the fields is controlled by the order that they are listed in the configuration file, so it may differ from the order that they appear on the html form.
6. The path specification to the configuration file is derived from a prefix (/var/www/data, for instance) configured into the script at time of installation, plus web server host name. This allows for use on multiple virtual sites on the same server.
7. The configuration file must already exist, and must be readable by the web server. For a 'normal' apache installation, should be owned by user, nobody, or on redhat linux, user apache. Permissions would then be 440 for apache.apache or for nobody.www
8. The configuration file name allows only upper, lower case, numbers and underscore.
9. All configuration moved to a config file instead of specified in the html form.
10. The only required field in the html form is 'c' to specify the config file name. I recommend using something less than obvious, but related.

Installation (for admin's)

1. Install the script in the server's cgi directory, and adjust the permissions to suit.
2. Edit the script to perform any needed customization. See below.
3. Create a directory for configuration files. This directory must be readable by the web server. The script is currently set up to look in a subdirectory based on the server name.
4. For instance, if the cfgdir is /var/www/domail, and the host is grox.net, the config file should live in /var/www/domail/grox.net.
5. Edit the $cfgdir variable to point to the configuration directory.
6. If necessary, edit the $mailer variable to point to the MTA.

Use (for users)

1. create the form. the action tag should include the url for script, either relative or absolute. either GET or POST may be used as the method. insert a hidden field named 'c' with the name of the configuration file. Example:
   <form method="POST" action="/cgi/domail">
<input type="hidden" name="c" value="form.cfg">
2. If they do not already exist, create the header and footer templates.

   Sample header template <html> <head> <title>my mail form </title> </head> <body bgcolor="black" text="white"> <img src="mybanner.gif"> <!-- end header -->

   Sample footer template <!-- begin footer --> <p>page last updated: YESTERDAY</p> <p>copyright 1980 by me</p> </body></html>

3. Create the redirect and error pages.

   Sample confirmation page <html> <head> <title>Your mail has been sent</title> </head> <body bgcolor="#ffffff"> <h2>Thank you!</h2> <h3>Your mail has been sent.</h3> <a href="/">GROX home</a> </body> </html>

   Sample error page <html> <head> <title>Error: Mail not sent</title> </head> <body bgcolor="#ffffff"> <h2>Error</h2> <h3>Sorry, your mail could not be sent.</h3> INSERT_ERROR_MESSAGE_HERE <a href="/">GROX home</a> </body> </html>

4. Create the configuration file, noting file permissions. More information below.
5. test *thoroughly*

Lines have the format 'setting=value' where setting is one of the settings specified below. Settings are case-sensitive. 'value' can be anything, and can include whitespace and odd characters (tho' their use is deprecated). Long lines *must not* be wrapped. Each value must be contained on a single line. There is no length restriction. Lines that begin with a sharp (#) are ignored, and can be used to document the configuration with comments. Blank lines are also ignored.

Configuration settings

to

email recipient. who should receive the email

metoo (not yet implemented)

if the field 'email' exists, also send mail to that address. note that no validity checking is performed on the address. valid values for this are yes, YES, y, Y. the mail will not be sent for any other value here.

subject

the subject line that is to appear in the mail message sorry, not able to generate dynamic subjects at this time.

fields

comma delimited list of fields. field names must not contain spaces, and should contain only alpha-numeric characters. fields should be listed in the order that they should appear in the email.

required

list of fields that must contain a value or the user is redirected to an error page.

header

header file to include for site look 'n feel. this file should contain no SSI, only simple HTML. this must be a fully-qualified path specification to the file such as /var/www/site/my.cfg.

footer

footer file to include for site look 'n feel. see the description for the header file.

okfile

file name (full file spec) of the page that users will be shown on successful processing of the form.

errfile

file name (full file spec) of the page that users will be shown when an error is encountered. this page may contain the tag: INSERT_ERROR_MESSAGE_HERE where an error message will be inserted. this page must not contain any SSI, since it will not be subject to SSI processing.

  # sample configuration file for domail script

  # the email will be sent to this address
  to = dave@grox.net

  # if there is a field named 'email', send a copy of the mail
  # to that address also
  # NOTE: not currently implented
  metoo = yes

  # subject line for the email
  subject = Email from the web site

  # field names in the form. order that they appear here determines the
  # order they will be included in the email message.
  fields = Name,Email,message,signup,phone,address,address_1,address_2

  # list of fields that must not be blank. if they are, the user is given
  # a message that is inserted into the errfile template.
  required = Name,Email

  # these determine look 'n feel
  header = /var/www/mysite/lib/header.html
  footer = /var/www/mysite/lib/footer.html

  # these are the pages that are displayed on
  # success and failure respectively
  okfile = /var/www/mysite/lib/redirect.html
  errfile = /var/www/mysite/lib/error.html

The script contains a customization section near the top of the file where a few settings may be adjusted for the site. These must be set before attempting to use the program.

The list of servers must be adjusted to only allow the web servers where the script is used. If this is not changed, only my hosts may use your script. ;-)

The directory where configuration files are kept must be set. Though the information in this file is not particulary sensitive, it should not be accessible from the web to prevent tampering with the settings. The path is hard-coded into the script to prevent others from using an arbitrary path, thus perverting the script's operation in some fashion.

The name of the web server is appended to the path to the script so that the same top level directory may be used for multiple virtual hosts on the same server.

Optionally, one may change the path to the MTA (sendmail program) if another program is in use. Note that some other programs might require a change to the command line arguments used to call them from the script. This may be adjusted by editing the call that opens the $mailer file near the end of the script.

Near the top of the script, a $debug variable exists that can be changed from 0 to 1 to obtain intermediate messages. These can be used to diagnose problems with the installation. This should definitely be turned back off before production use.

enjoy!
...dave