iTools - Beginner's Guide: Installing A Form To Email Processor

After getting their web server up & running to it's most basic point (i.e. serving up their web site), most new server administrators usually start expanding their abilities on their new server by getting a little more fancy with their websites - after all, what's the point of running your own server unless you can have some of that extra stuff on your website.

Far & away the most popular new facility that people have after they start to expand their website is a form to email processor. Formerly, I used to recommend scripts which were found at Matt's Script Archive. However, there have over the years been found a good many security issues associated with Matt's Formmail.pl script & as such, a more secure alternative is in order.

iTools users, owing to Mac OSX' *nix underpinnings, are very lucky to have thousands of high quality open source scripts, in addition to thousands of commercial scripts, both of which can be readily customised for your needs, so you might like to search for something else, but for the purposes of this tutorial, FormMail.pl is enough to start off with. The guide should work for the inbuilt Postfix mail server that's standard with iTools if you're running OSX 10.3.x, Tenon's Post.Office & also Sendmail under OSX 10.1.x onwards

After reading through this guide, take a look at the tips & troubleshooting sections at the end of the guide, which may assist if you run into trouble.

Fortunately for us, a team of Perl programmers (the London Perlmongers), dubbed NMS, have put together much more secure scripts to take the place of Matt Wright's scripts, which were mostly produced in the early days of the Internet popularity boom & security was not much of a concern. Appropriately, one of these replacement scripts is called - FormMail, which we're heading off into now.

To download the script, head on over to nms-cgi.sourceforge.net & navigate your way to the link which is called 'The Scripts' - scroll to find the script called FormMail & then download the tarball to your hard drive. Whether you are downloading the file direct to your server, or to another machine, you can expand the tarball archive with something like Stuffit Expander, or use a terminal command like:

# tar zxvf formmail_compat-3.11c1.tar.gz

The package contains a few files, but the important ones are thee ReadMe file & of course the one labelled FormMail.pl - this is the actual script that you'll be putting into the CGI execution directory on your server, so it's a good idea to make a backup before editing anything (of course if you've kept the tarball intact, you've already got yourself a backup anyway).

My preference is to make a copy of the script & upload it to your cgi-bin (which under iTools 7.x is currently:

/Library/Tenon/WebServer/cgi-executables

So, take a read through the ReadMe file & try to understand all the options & information that is listed out in that file, then load up the actual script either in a text editor, or from the command line, use this command:

# pico FormMail.pl

This will open up a command line text editor which will give you the correct linebreak format - TextEdit should do the same, but if you're using anything else, be sure that you are using Unix style linebreaks.

In particular, there are a few options near the top of the file which will definitely need to be edited, particularly these lines:

$mailprog = '/usr/lib/sendmail -oi -t';
$postmaster = '';
@referers = qw(dave.org.uk 209.207.222.64 localhost);
@allow_mail_to = qw(you@your.domain some.one.else@your.domain localhost);
@recipients = ();

The $mailprog line needs to be changed for our iTools system - even if you are using Postfix which comes with OSX 10.3, or Tenon's Post.Office, the sendmail program has a compatible mail sender program which uses a similar path. To find out the path you need to insert for your system, use this command, which will spit out the correct location like so:

# which sendmail
/usr/sbin/sendmail

Now of course, you need to change the line to accomodate the correct mail path for your server so it reads like this*:

$mailprog = '/usr/sbin/sendmail -oi -t';

It's always a good idea to insert a postmaster email address should things go wrong - as you are most likely the person running your mail server if you're doing this tutorial, insert the postmaster email address into the appropriate line, or your own email address if that's what your postmaster is linked to like this:

$postmaster = 'postmaster@yourdomain.com';

Similarly, you will only want to allow the forms to be utilised by your own network, or by people who are visiting your website, so you'll want to insert the appropriate info into the @referers line:

@referers = qw(yourdomain.com 192.168.0.2 localhost);

While not foolproof, this helps to ensure that your form isn't hijacked by a malicious person to be sending out spam email to all & sundry.

The @allow_mail_to field is a little similar, hard-coding a chosen email address (usually yours), into the form, adding another security precaution to your script so that form submissions are only sent out to the email address you've entered there:

@allow_mail_to = qw(you@yourdomain.com);

It's possible to enter a number of email addresses, each separated by a space, if you wish to send form submissions out to more than one person.

If you're familiar enough with Perl, check the Readme file for information on the @recipients field, which adds just that bit more security to your script - it won't matter if you leave it empty, the script will still work, but it's worth looking at down the track.

Now, you should be set to try your script out, but first, you need to set the correct permissions for your script to execute. Again from the Read Me file, you'll find a line which should do the trick for you as follows:

# chmod +x FormMail.pl

Entering the usual chmod 755 FormMail.pl instead should also work.

Once you've done that, you need to create an HTML page which contains a form to test out your script. If you've taken the time to check out that Read Me file, they've kindly included some suitable & easily modified HTML for a form, so you can do a cut & paste job into an HTML file & modify the appropriate fields, such as entering your domain name etc... as well as specifying a suitable receipient address (i.e. your own) for the form to correctly reference your script.

So, load up your favourite browser & enter the appriate URL for your test form page, which if you used the suggested example in the Read Me file, should look like this:

If that's appeared, you're almost there - check your email you should see the results of your feedback form appear & that's it, so congratulations. You're on the way to using FormMail with your own HTML forms, so now start experimenting - perhaps making a copy of your working script, but you probably don't need to modify anything else, simply creating your own custom forms & FormMail will handle the output.

I hope this guide helps you get a bit more out of your webserver. Now you have the basics to start looking at more advanced scripts to install.

Tips

A small tip for those new to servers - one of the most basic security precautions you can take when installing your FormMail script is to change it's name. Many potential hackers attempting to misuse your FormMail script (owing to the insecurity of the old Matt Wright FormMail script). Viewing your webserver's error logs over a given period will no doubt reveal a pile of calls to FormMail.pl, FormMail.cgi or variations, so a simple namechange will assist by not letting potential hackers know that you're running a new FormMail.

Of course, don't forget to refer to that new name when calling your script from your HTML forms.

* Troubleshooting

I've had feedback from some people that the -oi -t flags on the end of the $mailprog line don't work under Postfix - I don't know why, because it works for certain on my system - if you strike this problem, simply remove the o from -oi so the line reads:

$mailprog = '/usr/sbin/sendmail -i -t';

Also, a gotcha that's bitten me a few times. If for some reason, you get errors after following this script through, there are a few possibles. Firstly, make sure that you've uploaded your script to the server as an ASCII text file - uploading as raw binary will cause you no end of grief, as your server will almost certainly generate end of script headers or something similar.

You will also need to make sure that your forms include at the very least, a recipient field, as FormMail plain won't work without it.

iTools - A Beginner's Guide: Installing A Form To Email Processor