Installing NMS FormMail

Writing up the HTML source code to render a simple feedback form is only half the job. Now you will have to install a form mail script that will actually process the contents of the form when the user clicks on the Submit button. For the following tutorial, we'll use the NMS FormMail script. You can download it here:

You'll need a zip file program to unpack it. If you don't have one then do one of the following:

• Download EasyZip — EasyZip is a powerful and easy-to-use zip and unzip utility for Windows.
• Download the trial version of WinZip — This is the more popular and full featured zip file utility.

Requirements

To run through this tutorial, you will need:

1. A web host with a Unix or Unix-type server
   (More information please...)

   Unix or Unix-type servers

   
   Most web hosts have Unix or Unix-type servers. Unix or Unix-type refers to the operating system your web host's server computer is running. This tutorial applies to Unix or Unix-type systems like Linux, Redhat, FreeBSD, OpenBSD, Fedora to name a few. If you don't know what OS your web host server is running then just visit the Netcraft Web Server Query page and enter your domain name into the "What's that site running?" box.
   
   Windows
   NMS FormMail can be installed on Windows servers but I don't have any experience with this (sorry). However you may find the following information useful:
   
   

   • Perl scripts generally do not require the shebang line (path to Perl) in order to run on Windows servers as the .pl file extension automatically indicates to Windows where to find the Perl interpreter. The exception to this is if the Windows server is running Apache in which case the shebang line would be the system path to Perl (typically #!perl or #!C:\perl\bin\perl.exe )
   • Windows servers don't use the Sendmail program (instead they use an SMTP relay or another program)
   • Setting file permissions for the Perl script is not necessary because permissions are inherited from the Windows OS.

   
   
   (Click to close)
   
   
   
   
2. A secure cgi-bin directory
   (More information please...)

   Secure cgi-bin

   
   cgi-bin (sometimes called cgi or cgi-lib) is a directory that is specially configured by your web host to run scripts for your website. To be truly secure, it should be located one level up from your document root directory (the root folder where you keep your .html files) and it should not serve up static content. To verify this, see if you can access a directory listing by entering the following:
   
   

   http://www.your_site.com/cgi-bin/

   
   ...into the address bar of your web browser and then hit GO (replace www.your_site.com with your domain name). Then try uploading a web page (any one, doesn't matter) called test.html to your cgi-bin and then see if you can access it by typing the following URL into the address bar of your web browser and hitting GO:
   
   

   http://www.your_site.com/cgi-bin/test.html

   
   In both of the above scenarios you should be confronted with a 403 Forbidden message (or something similar) which means your cgi-bin is fairly secure.
   
   Ive seen some appalling situations where web hosts will simply create a new directory called cgi in the document root directory and then just leave it wide open for anybody to walk in and have a good look around. If your situation is similar to this then run like the wind to find another web host.
   
   (Click to close)
   
   
   
   
3. A good text editor
   (More information please...)

   A good text editor

   
   You'll need a good text editor that can handle large file sizes (Windows 9x Notepad can only handle up to 32K) and preferably has the option to save with Unix line endings (no version of Windows Notepad can explicitly do this). If you don't have a text editor that can do both of these then may I suggest Metapad which is an excellent high-powered fast loading replacement for Windows Notepad. You can download it here:

   Download Metapad zip file

   To convert to Unix line endings in Metapad, click on File » File Format » UNIX Text (LF) or press Ctrl + 2 on your keyboard.
   
   (Unix line endings may not be an issue depending on which version of Perl your web host is running but it's always best to be on the safe side and save Perl scripts with Unix line endings no matter what.)
   
   
   (Click to close)
   
   
   
   
4. A spirit of adventure and a little patience...
   (More information please...)

   Patience, my friend...

   
   If you don't have alot of experience installing Perl scripts then you probably took one look at the NMS FormMail README file, fell off your chair (after you fainted) and then crawled away to some quiet place to coddle your spirits. Keep in mind that THIS IS NORMAL.
   
   So if after running through this tutorial you start getting a plethora of error messages including the dreaded 500 Internal Server Error then do not despair. To the uninitiated, installing a Perl script may seem like rocket science but more often than not your feedback form is malfunctioning merely because you made some kind of minor omission or typo in the FormMail.pl USER CONFIGURATION SECTION.
   
   Just remember to stay calm and objective, and have the patience to persevere through a few basic debugging steps and you'll have your feedback form up and running in no time. Others have gone before you and survived. You can too.
   
   
   (Click to close)
   
   
   
   

Installation

First of all be advised that this step-by-step tutorial will help you set up a bare-bones, no-frills installation of NMS FormMail. It is specifically designed to get you from point A (overwhelmed with the idea of installing a Perl script) to point B (receiving your first email from your feedback form) as quickly as possible. It is not intended to replace the comprehensive README and EXAMPLES documentation that comes with your zip file package.

Okay let's get to it. Assuming that you have a feedback form page all ready to go and you have downloaded and unpacked the zip file ( see above) then here's how to install NMS FormMail:

1. Verify program paths ~ Refer to the documentation that your web host sent you when you first signed up with them or contact your web host's technical support to get the following information:
   
   
   1. Path to Perl - This is typically /usr/bin/perl
   2. Path to Sendmail - This is usually either /usr/lib/sendmail OR /usr/sbin/sendmail
   
   If you don't know what either of these two are and you can't summon up your web host's technical support then see My Web Host is Out to Lunch for an alternative method of getting this vital information.
   
   
2. Open and edit FormMail.pl ~ Go to the folder to which you extracted the contents of your NMS FormMail zip file, open FormMail.pl in a good text editor (Shift + Right-click » Open With...) and make the following changes:
   
   
   1. The first line in a Perl script is known as the shebang line and basically tells the script where to find the Perl interpreter on your web host's server computer. By default, the first line in FormMail.pl should read:
      
      
      #!/usr/bin/perl -wT
      
      If your web host's path to Perl is NOT /usr/bin/perl then replace the part highlighted in red with the path to Perl that your web host provides.
   2. Next, scroll down a bit in FormMail.pl to locate the following line in the USER CONFIGURATION SECTION:
      
      
      $mailprog = '/usr/lib/sendmail -oi -t';
      
      If your web host's path to Sendmail is NOT /usr/lib/sendmail then replace the part highlighted in red with the path to Sendmail that your web host provides.
   3. Now let's define which websites are allowed to use your FormMail script. Once again in the FormMail.pl USER CONFIGURATION SECTION, locate this line:
      
      
      @referers = qw(dave.org.uk 209.207.222.64 localhost);
      
      Replace the part highlighted in red with your domain name, e.g.
      
      
      @referers = qw(www.your_site.com);
      
      
   4. And finally, we are going to specify which email address to send the contents of the feedback form to when the user clicks on the Submit button. To do this, locate this line (USER CONFIGURATION SECTION):
      
      
      @allow_mail_to = qw(you@your.domain some.one.else@your.domain localhost);
      
      Replace the part highlighted in red with your email address, e.g.
      
      
      @allow_mail_to = qw(your_name@your_site.com);
      
      
3. Rename FormMail.pl ~ Malicious individuals (a.k.a hackers) have devised ways to locate newbie FormMail setups by searching web page source code for instances of "FormMail.pl" (usually found in the <form> start tag). Hence, as a security precaution, you should save your configured FormMail.pl file using any name that doesn't have the word "form" or the word "mail" in it (be sure to keep the .pl extension however). This will also preserve a default copy of FormMail.pl should something go wrong with your configurations and you have to start over. For demonstrational purposes, we'll use the name newname.pl
   
   
4. Upload newname.pl ~ Now that FormMail.pl is properly configured and given a new name (i.e. newname.pl), it's time to upload it to your website's cgi-bin directory. Make sure that you upload newname.pl in ASCII mode.
   
   
5. Set file permissions ~ Use the chmod command in your FTP program or use your website's control panel to change the file permissions of newname.pl to 755 (rwx r-x r-x). When setting file permissions, you will most likely be confronted with a dialog that allows you to set permissions to the selected file according to three categories: Owner, Group and Other. Beside each category will be three settings: Read, Write and Execute. Set them as follows:

   Owner - click to check Read, Write, Execute
   Group - click to check Read and Execute (clear Write)
   Other - click to check Read and Execute (clear Write)

6. Link feedback form to newname.pl ~ Your feedback form will need to know where to find the processing script to use (in this case, newname.pl) when the user clicks on the Submit button. This is accomplished by editing the value of the action attribute of the <form> start tag. If you followed the tutorial on the previous page on how to create a simple feedback form, your <form> start tag should read as follows:
   
   
   <form action="URL to form script" method="POST">
   
   Replace URL to form script with http://www.your_site.com/cgi-bin/newname.pl (where www.your_site.com equals your domain name), e.g.
   
   
   <form action="http://www.your_site.com/cgi-bin/newname.pl" method="POST">
   
   
7. Upload feedback form page ~ Instead of immediately "going live" with your feedback form, it's best to create a "test" directory at your website and then upload your feedback form page there. This way, if you've made any errors in the set up process, you can debug them privately before presenting the feedback form to the general public (and possibly to hackers looking for erroneous FormMail setups that they can easily exploit).
   
   
8. Load feedback form in your web browser ~ Assuming that you named your feedback form contact.htm and uploaded it to a directory named "test" (as per step #7) then you can load it by typing the following into the address bar of your web browser and then click GO:
   
   http://www.your_site.com/test/contact.htm
   
   (Replace www.your_site.com with your domain name.)
   
   
9. Test run ~ Now simply fill in the form and click on the Submit button to test it out. If all goes well, you should be redirected to a Thank You page and you should receive the comments you entered in the form as an email to the address you specified in step #2(d).
   
   

What's that? All did not go well, you say? Well then don't panic. Let's just move on to some basic debugging...