NOTE: This is not a security check. Referer headers can EASILY be faked. Rather, it prevents someone on xyznotyou.com from using the FormMail on your server to process forms on their server on a regular basis. It remains in the script as a remnant of earlier versions when it was used for security, but the @recipients variable is now used to specify exactly who can receive e-mail from this installation.

As of version 1.7, the domains listed here are also used as the defaults when checking valid recipient e-mail addresses. You should either include all domain names that you wish to have FormMail send e-mails to in your @referers array or tailor the @recipients array by hand.

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 a user was 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.

@recipients is the most important variable you need to configure. It is an array of regular expressions defining all valid recipients that can be specified. In order for an e-mail to be sent to the recipient defined in a form, the recipient e-mail address must match one of the elements in the @recipients array.

SIMPLE SETUP:

For the most simple setup, place any domain name that you wish to send form results to in the @referers array. Warning: This allows those domains to also access your FormMail script and utilize it to process their own forms, but likely this is what you intended anyway. If so, you can leave:

@recipients = &fill_recipients(@referers);

Another alternative, then, is to set @recipients equal to the return value of the fill-recipients function and pass this function all of the domains to which e-mail may be addressed:

@recipients = &fill_recipients('domain.com',
                               'sub.domain.com','another.com');

Similarly, since @recipients is just an array, you could even do:

@recipients = (&fill_recipients('domain.com','sub.domain.com'),
               '^otheruser1@otherhost\.com',
               '^otheruser2@otherhost\.com');

HOW DOES THAT WORK?

When the fill_recipients function is called on an array of domain names, it turns them into regular expressions. These regular expressions will only allow e-mail messages to go to a recipient with an e-mail address in the following format:

[A-Za-z0-9_-\.]+@domain.com

where domain.com is specified in @referers. For any IP addresses in @referers, the following address formats are valid:

[A-Za-z0-9_-\.]+@[192.168.1.1]

where 192.168.1.1 is the specified IP address in @referers.

What this means in english is that the only valid addresses are those to usernames that include only letters, numbers, underscores, dashes or periods and an exact domain name or IP address that was specified in the @referers array. Depending on your needs, this may be too broad or not broad enough.

WHAT IF YOU NEED MORE FLEXIBILITY??

The way FormMail validates a recipient address is to check the supplied recipient(s) in the submitted form against each element in the array @recipients (which is a list of Perl regular expressions). If any valid recipients are found, they will receive a copy of the message.

Using the examples of @referers = ('domain.com','192.168.1.1'); and the default usage of setting @recipients = &fill_recipients(@referers), the contents of @recipients are now the same as if you had written:

@recipients = ('^[\w\-\.]+\@domain\.com',
               '^[\w\-\.]+\@\[192\.168\.1\.1\]');

VALID:

user@domain.com, First.Last@domain.com,
Last-First@domain.com, user_name@domain.com,
user023@domain.com, user@[192.168.1.1], 
First.Last@[192.168.1.1], user023@[192.168.1.1], 
Last-First@[192.168.1.1], user_name@[192.168.1.1], etc.

user%name@domain.com, user(name)@domain.com,
first:last@domain.com ,
domain.com, user@192.168.1.1,
user@newdomain.com, user@sub.domain.com,
user@domainname.com

BUT I NEED TO MATCH MORE CHARACTERS IN THE USERNAME!

Let's say you need to be able to deliver e-mail to an address like: last:first@domain.com

This requires that the ':' character now be allowed into the portion of the recipient field before the domain name. You could then modify @recipients to read:

@recipients = ('^[\w\-\.\:]+\@domain\.com');

Allowing certain characters could be VERY dangerous, especially if the characters are: %, <, >, (, ) or any newlines. You can read: http://web.nps.navy.mil/~miller/percent-hack.html
for information on exactly why the % character could be dangerous. And the document that prompted 1.91 explains why some of the others could lead to problems: http://www.monkeys.com/anti-spam/formmail-advisory.pdf

I ONLY WANT CERTAIN ADDRESSES TO WORK!

Let's say you only want yourself@yourdomain.com to be able to receive any form submissions. You should then set the @recipients array to:

@recipients = ('^yourself\@yourdomain\.com');

If there are several, simply do:

@recipients = ('^user1\@yourdomain\.com',
               '^user2\@their\.domain\.com');

Prior versions of FormMail recommended settings for @recipients like:

@recipients = ('domain.com','192.168.1.1');  OR
@recipients = ('^joe@somewhereelse.com');

WHAT IS THIS ^ CHARACTER AND WHY SO MANY \'s??

In regular expressions, the ^ means "beginning of string". By default, FormMail places a $ at the end of the match, which means "end of string". By using both ^ and $ in regular expression matching, FormMail can match a string exactly. You only need to worry about including the ^, which is STRONGLY recommended for all regular expressions in the array.

The \ character is used to escape a character that otherwise means something special in regular expressions. For instance, you now see every '.' being escaped with a '\', as '.' means ANY CHARACTER, whereas '\.' requires that it match ONLY a period.

If you need a regular expression matching solution even more specific than the above examples explain, I recommend picking up a book on Perl.