FormMail

FormMail

What is FormMail?

FormMail is a generic WWW form to e-mail gateway, which will parse the results of any form and send them to the specified user. This script has many formatting and operational options, most of which can be specified through the form, meaning you don't need any programming knowledge or multiple scripts for multiple forms. This also makes FormMail the perfect system-wide solution for allowing users form-based user feedback capabilities without the risks of allowing freedom of CGI access.

We have chosen to distribute to Golden Triangle clients a version of formmail provided by Monkeys.com. They have altered the original script from Matt's Script Archive to provide additional security. Although Matt's formmail v1.9 is very functional, it is known to be relatively insecure and can be exploited to send Spam that appears to come from the host website. You can read more about this issue at http://www.monkeys.com/anti-spam/filtering/formmail.html.

We have made small changes to the script provided at Monkeys.com in that we have pre-entered default e-mail addresses at Golden Triangle and adjusted the path to sendmail. It is imperative that you follow the steps below and ensure you enter your own information into the script, otherwise you will not receive data submitted via your form/s.

##############################################################################

Form Configuration:

The Script should be placed in one of the publicly accessible directories in your website. The action of your form must point towards the script and the method must be POST or GET in capital letters. FormMail offers many ways to tailor the resulting HTML page and the way the script performs. Check the documentation included with the script for more details regarding it's use.

Necessary Form Fields:

First of all, to get you started you should have a line resembling this one at the beginning of your form.

Other than that, there is only one form field that you must have in your form, for FormMail to work correctly. This is the recipient field.

Field: recipient

Description: This form field allows you to specify to whom you wish for your form results to be mailed. Most likely you will have to configure this option as a hidden form field with a value equal to that of your e-mail address.

Syntax:<input type=hidden name="recipient" value="email@your.host.com">

Optional Form Fields:

subject
email
realname
redirect
required
env_report
sort
print_config
print_blank_fields
title
return_link_url
return_link_title
missing_fields_redirect
background
bgcolor
text_color
link_color
vlink_color
alink_color

Any other form fields that appear in your script will be mailed back to you and displayed on the resulting page if you do not have the redirect field set. There is no limit as to how many other form fields you can use with this form, except the limits imposed by browsers and your server.

Very Important Notes:

When uploading to your domain space, please set the host name to your domain name.

hostname: www.your_domain_name.com
username: web_server_user_name
password: ******** (The web_server_user_name password)

While uploading CGI scripts, .htaccess files, or .htpasswd files, set your FTP client's transfer mode to ASCII. This will convert Windows/Macintosh text files to Unix text. Graphics, and other 'binary' files should always be uploaded using 'binary' mode.

For your scripts, do not use a /cgi-bin/ folder. This would confuse the Apache Web Server. Make a /scripts/ folder or something similar, and put your scripts in there, just as you would have used a /cgi-bin/ folder.

##############################################################################

Setting Up the FormMail Script:
===============================

#There are three areas of the FormMail.pl available from ftp://ftp.golden.net that must be modified; the $mailadmin, the #@recipient_addresses, the @recipient domains and the @valid_ENV fields.

#It is very highly recommended that you read through the entire README so as to gain a better understanding of the security #issues with previous versions of Formmail.

#Thank you to monkeys.com for allowing us to distribute the more secure 1.9s version of formmail they created to Golden Triangle #clients. We have altered the script so that the default addresses and domains are entered. YOU NEED TO CHANGE THESE VALUES #AS SHOWN BELOW. Failure to do so will result in form submissions not reaching you and possibly having the form disable by Golden #Triangle until it is properly configured.

Necessary Variables:
--------------------

$mail_admin = ("your.email\@yourdomain.net");

This variable must define the (local) e-mail address of the local
e-mail administrator. IMPORTANT: The default definition of this
variable may perhaps NOT be valid or usable for your particular
system, so you may perhaps need to set this to something other than
the default value given in the distributed FormMail script.
ie.. change it to read: ("youremail\@yourdomain.net") including
the brackets and the \ . The backslash is Absolutely necessary as a security measure.

Regardless of what local e-mail address you set this to, please
_test_ that the e-mail address you use is in fact a working local
e-mail address. You should test it by logging into the *web server*
where you are installing FormMail and then trying to send a test
e-mail message to the $mail_admin address. Then check and make sure
that the message was properly received by the local mail administrator.

The value of this variable will be used as the place to direct e-mail
notifications regarding incorrect uses (and possible attempted abuses)
of FormMail. It is important that the e-mail address used be one that
is associated with some mailbox that is routinely and frequently moni-
tored by a live and concious human being.

NOTE! NOTE! NOTE! If you don't have a working postmaster address on
your local mail server, then for God's sake GET ONE! Internet RFC
standards absolutely REQUIRE that each mail server have a valid and
working postmaster address that goes to a live human being.

@recipient_addresses = ("your.email\@yourdomain.net");

This variable should be defined to an array of strings that represent
full and complete e-mail addresses of specific users (or accounts) that
should be allowed to receive e-mail messages generated by FormMail.
Each such address should have one the following forms:

user@domain

If the @domain part is ommited, the user part will be treated as the
user-ID of some local user account (or some local e-mail alias) on
the local system where FormMail is installed.

In either case, the user portion and the domain portion (if present)
will be syntax checked by FormMail, and users will receive errors if
any one of the pre-configured strings in @recipient_addresses
has invalid syntax. Domain names may only contain letters, digits,
hyphens (`-') and periods, as per Internet standards. (Note that
underscore characters are NOT valid domain name characters.) User
names can contain almost any characters except those that are reserved
and generally disallowed in Internet e-mail addresses, namely the
characters:

( ) [ ] < > { } : ; @

Note that unlike prior versions of FormMail, comparison of the user
portion of e-mail addresses is now perform in a CASE-SENSITIVE manner,
and thus the e-mail address "john@example.com" is NOT considered to be
equivalent to "JOHN@example.com" anymore. If you want to allow people
writing HTML forms that will interact with FormMail to use various
capitalizations, you will have to include each differently-capitalized
version of the address in @recipient_addresses. (This change was needed
in order to close a security loophole.)

Note also that unlike prior versions of FormMail, you CANNOT and MUST
NOT put any up-caret (^) character at the front of the e-mail address
strings that you use to define this array.

@recipient_domains = ('mydomain.com','mydomain2.com');

This variable should be defined to an array of strings that represent
the actual domain names, or patterns for the domain names (see below)
that you wish to allow FormMail to send e-mail to.

If you know ahead of time all of the exact and complete e-mail addresses
that you will want FormMail to be able to send e-mail to then DO NOT
use this variable - leave it set to an empty array (signified by just
an open/close pair of parentheses). Use the @recipient_addresses array
(described above) instead. That will be more secure.

There are cases however where the FormMail installer may be installing
FormMail so that it can be used by a lot of different people within a
given domain. (This comes up, for example, when the person installing
FormMail is doing so for the benefit of a web hosting company where
there are going to be a lot of different possible FormMail users.) In
these cases it is OK to use the @recipient_domains variable.

Each string used to define the @recipient_domains variable MUST have
one of the following two general forms:

domain
*.domain

where `domain' is some fully-qualified Internet domain name.

Use the first form shown above when you know the exact domain name that
will be used as possible recipient addresses for all Formmail-generated
e-mail messages.

In some cases, you may not know ahead of time (i.e. when you are instal-
ling FormMail) all of the possible fully-qualified domain names that you
may want to allow FormMail to send e-mail to, but you may know that they
will all be sub-domains of a given (base) domain. In such cases, you may
use the second form of string, shown above, which is an asterisk followed
by a period, and then a domain name. In this case, the asterisk is in-
tended to represent a sort-of `wild card' character, and this form, when
used, will allow FormMail to send e-mail messages to any e-mail address
whose domain part is any sub-domain of the specified base domain.

Note that you MUST NOT try to put multiple asterisks into any of the
string values given as part of the @recipient_domains definition, and
also, you are not allowed to put askterisks into random positions within
and of these strings. Only a single asterisk is allowed, and only at
the very start of each string used in @recipient_domains, and it must
be followed by a period and then a valid (base) domain name.

In either case, the domain name portion of the string will be syntax
checked by FormMail, and users will receive errors if any one of the
pre-configured strings in @recipient_domains has invalid syntax.

Domain names may only contain letters, digits, hyphens (`-') and periods,
as per Internet standards. (Note that underscore characters are NOT
valid domain name characters.)

SPECIAL NOTE: In order to close some security loopholes, whenever a
recipient address is submitted to FormMail (as part of an HTML form
submission), FormMail will check to see if the address matches one of
the allowed recipient specfications that you have edited into the script
as definitions for the @recipient_addresses and @recipient_domains arrays.
If a given recipient address matches _only_ one of the specifications
contained in the @recipient_domains array, then the given e-mail address
will NOT be allowed to contain any percent-sign (%) or any exclamation-
mark (!) characters. (Generally, this won't be a problem, because very
few people these days have e-mail addresses that include either of these
kinds of special characters.)

@valid_ENV = ('REMOTE_HOST','REMOTE_ADDR','REMOTE_USER','HTTP_USER_AGENT');

This new array allows the administrator to specify a list of environment
variables that the user may request be added into the e-mail. This is
a security patch that was advised against at:
http://www.securityfocus.com/bid/1187 and was implemented by
Peter D. Thompson Yezek at http://www.securityfocus.com/archive/1/62033
Only environment variables listed in this array may be included in the
form field env_report. So if you wanted to also know what URL they were
submitting from, you could change @valid_ENV to:
@valid_ENV = ('REMOTE_HOST','REMOTE_ADDR','REMOTE_USER',
'HTTP_USER_AGENT','HTTP_REFERER');
and then include HTTP_REFERER in your env_report form field.

Your FormMail program is now configured.

-----------------------------------------------------------------------------

##############################################################################

199.166.210.75 is the IP Address of cobalt.golden.net, the Golden Triangle Virtual domain server that hosts your domain name.

After upload, your content can be viewed through a Web browser at http://www.your_domain_name.com or http://cobalt.golden.net/~web_server_user_name

If the changes you have made do not show up in your Web browser right away, you may have to clear the cache in your web browser. Also try holding down the key on your keyboard, and click the "Refresh" or "Reload" button in you Web Browser. This should refresh the new content.

Downloads:

FormMail 1.9s and Read Me Files can be downloaded here: This is the more secure version that you may use on websites hosted by Golden Triangle. Remember to make the adjustments to the fields as shown above.
NOTE: A preferable method of downloading the formmail script is to use an ftp client like WS FTP and ensure that you conduct the download using ASCII mode, NOT binary.

See an example of FormMail

Matt's Script Archive - http://worldwidemart.com/scripts

Monkeys.com Formmail Page