Superfrm.pl is a form processor script. It is designed to allow you, the webmaster, to easily setup multiple form processors on one or more servers. These servers can be under the same or different domains. The script will read the form sent to it, make sure all required fields are filled out ( it will show an error page on the user's browser if they are not), send an autoreply to the user who successfully fills out the form, and send an email of the user's responses to someone. The error page, autoreply form, email, subject, and sender address are all customizable!
Superfrm.pl allows you to specify your own files for the autoreply, email form, and error pages. Not only can you use your own forms, you can use data from the user's input in all of these templates as well. This allows you to easily tailor your autoreply, form output, and error pages to suit you and your users' needs. Additionally, you don't have to specify klunky full paths to your files ... you can use URLs and the script will retrieve them from a web server anywhere on the Net! All the form parameters you need to specify can be hidden in your HTML files using <INPUT TYPE=HIDDEN> tags. This lets you set up multiple forms wihtout having to edit server-side configuration files.
Superfrm.pl also gives you five security features to help keep crackers from abusing your script. The first is access control; a field in the configuration file allows you to specify machine and or domain names of machines that are allowed to use your script to process their forms (CGI http referer variable). The second is the ability to specify an artifical root directory for file locations to keep outsiders from trying to abuse your form processor and get it to send them important system files like /etc/passwd. The third, superfrm.pl has logging and debugging features built in. The logging feature tells you when specified template files could not be retrieved, who is using the script, when an unauthorized user has accessed your script, and when a bad email address has been entered. The fourth feature is that the script will only allow hosts (http host CGI variable) in the allow list to use the script. The final feature is the ability to specify a list of IP addresses and IP address patterns of clients that may not use the script (CGI remote addr variable).
Superfrm.pl is designed to be easy to use; because of this the installation is a bit more involved than other scripts you may encounter. Don't worry, nothing here is rocket science and if you get stuck you can always email cgi-help@webwizarddesign.com for assistance.
Superfrm.pl uses three standard perl modules:
This script requires you have perl 5.004 or better (5.005+ preferred).
To see whether or not your perl is new enough, run this command from
the command line or ask your system administrator:
perl -v
If you see a message about unrecognized switch or your perl is version 4, ask your administrator to upgrade or tell you where the perl 5.00* executable is located ... some systems have both perl 4 and perl 5 installed. I recommend at least perl 5.00503 for this script, but earlier versions of 5.* should work fine.
perl -MNet::SMTP -e 1 perl -MLWP::Simple -e 1 perl -MCGI -e 1If you get error messages about not being able to locate a module in @INC, you do not have that module and need to install it. You can install the module in your home directory as a regular user or as root if you have superuser priveleges. To install a module, use the CPAN module of perl like this:
perl -MCPAN -e shellThis will give you a prompt of "cpan> " if the module is on your system. If it is not, ask your system administrator to install the modules, go to CPAN and install them yourself, or email us at cgi-help@webwizarddesign.com.
#!/usr/bin/perlChange the path and executable name to match your server's settings. Make SURE the line at the top of the script contains the full path to perl (If you don't know where perl is, ask your administrator. Now ftp the script to your cgi-bin directory (if you don't know where that is, ask your administrator), and make sure the script is mode 0755. To do this yourself, telnet in to your account and execute the command:
cd <directory where superfrm.pl is> chmod 0755 superfrm.pl
The superfrm.cf file contains administrative and security-related settings. It only needs to be setup once; all the HTML form processor commands are embedded in your HTML pages. There are eight important variables in the superfrm.cf file:
Example: # This turns security on CHECK_CLIENT=1
Example: # This lets my personal machine, all earthlink machines, and two machines from # www.org use my form processor. ALLOW=127.0.0.1,*.earthlink.net,foo.www.org,bar.www.org
Example: # No one from 192 network can use this and neither can 10.0.0.5 DENIED_ADDRESSES=192.*,10.0.0.5
Example: # By using this, if someone tries to request /etc/passwd, the script will # try to get /home/u/user/etc/passwd instead. This also lets me shorten # the path names I use when retrieving templates in my script. ROOTDIR=/home/u/user/
Example: # Our mail host is not local MAILHOST=mail.server.elsewhere.com
Example:
# Turn on logging
LOGGING=1
# Log to superfrm.log n the current directory (default) LOGFILE=./superfrm.logNOTE: If you do not want to make your log directory world-writable, you can use a SUID wrapper for superfrm.pl to let it run with the same privileges as your user account.
Example: # No debugging DEBUG=
Example: # Debug to /tmp DEBUGFILE=/tmp/superfrm.debSee the example directory for example config files.
You are pretty much free to make your form however you would like it; there are several fields that the script expects to see in any form it receives if it is to do anything useful. All fields that superfrm uses begin with `S.' so they stick out in your form. None of these are required, however, if you include none of them, the processor won't do anything with your form :).
Example: Enter your email address: <INPUT TYPE=TEXT NAME="s.email" SIZE=30 MAXLENGTH=30>
Example: Enter your FULL name: <INPUT TYPE=TEXT NAME="s.fullname" SIZE=50 MAXLENGTH=50>
Example: Enter your first name: <INPUT TYPE=TEXT NAME="s.first" SIZE=40 MAXLENGTH=40>
Example: Enter your last name: <INPUT TYPE=TEXT NAME="s.last" SIZE=40 MAXLENGTH=40>NOTE: If you do NOT put s.email in your form, you will not be able to have the script send an autoreply to the user. If you do not put either s.fullname or both s.last and s.first in your form, you will not be able to access the user's FIRST, LAST, and FULLNAME in your script using the $first, $last, and $fullname variables.
These form fields allow you to completely control the behavior of the form processor through your HTML form using INPUT TYPE=HIDDEN tags. All options listed are optional, though some options rely on others. Here is a list of the options you can use in your HTML forms: remember that all administrative options start with `S.':
Example: <!-- Don't send an email of the form output in this form --> <INPUT TYPE=HIDDEN NAME="S.NOMAIL" VALUE=1>
Example: <!-- Don't send an autoreply in this form --> <INPUT TYPE=HIDDEN NAME="S.NOREPLY" VALUE=1>
Example: <!-- Email the form output to this person --> <INPUT TYPE=HIDDEN NAME="S.MAILTO" VALUE="nobody@noserver.net">
Example: <!-- These fields must all be filled out --> <INPUT TYPE=HIDDEN NAME="S.REQFIELDS" VALUE="EMAIL,FIRST,SHIRTSIZE">
Example: <!-- Email from this form should come from here --> <INPUT TYPE=HIDDEN NAmE="S.MAILFROM" VALUE="me@mehost.com">
Example:
<!-- This form should be sent to the administrator using the name
and email address of the person submitting the form -->
<INPUT TYPE=HIDDEN NAME="S.FORMFROMSENDER" VALUE=1>
The template location tags go in your form along with the other tags listed above; all are optional. If you do not specify files for any one of these, default pages will be used.
Example: <!-- Use the form on our sister site as an email template --> <INPUT TYPE=HIDDEN NAME="S.MAILFORM" VALUE="http://sistersite.com/mailform.txt">
Example: <!-- Use the form on our server site as an autoreply template --> <INPUT TYPE=HIDDEN NAME="S.MAILFORM" VALUE="/usr/docs/us.com/frm/autoreply.txt">
Example: <!-- Use the form on our server site as an error page template --> <INPUT TYPE=HIDDEN NAME="S.MAILFORM" VALUE="/usr/d/us.com/errorpage.html">
Example: <!-- Use the form on another server as an thank you page template --> <INPUT TYPE=HIDDEN NAME="S.THANKS" VALUE="http://localhost/forms/thanks.html">Whew ... that may seem like a lot, but once you get used to it, you will be putting up forms in no time! On to variables and templates :)!
Now the neat part ... all the fields YOU specify in your form are also available for use in your templates!! If you specify a field named SSN in your form, it is available as the variable $ssn in your form! All fields from your form are available in the same way ... just put a `$' dollar sign in front of the all lowercased field name and voila!
Any value that is present in both your HTML form and template will be used in the template by substituting the variable with the value of that variable. If the variable is NOT present in the form but IS listed in your template, it will be substituted with nothing (empty string). You can specify a default value to be used in your templates if the variable requested is NOT found in your form like this:
${variable:-default value}
Whoops, ${first:-kind user}, you missed the following fields:
$field_list
Please go back to the form and fill out these fields before resubmitting
the form ... thanks!
Templates allow you to specify your own files for the error page, autoreply form, emailed form, and thank you page. They are called templates because you can specify the special words (variables discussed above) in them and the variables will be replaced by text from your form, allowing you to customize them using the user's input. The forms listed in these tags can be either full paths and file names to files on your server,
Example: <INPUT TYPE=HIDDEN NAME="s.mailform" VALUE="/home/u/user/mailform.txt">OR absolute URLs of files anywhere on the Internet:
Example: <INPUT TYPE=HIDDEN NAME="s.mailform" VALUE="http://www.cya.com/templates/mailform.txt">NOTE: In order for the script to read the file listed as a URL, you MUST start the URL with http:// !!!
Check out the examples directory for
sample forms and templates.
You can get help on using this script by sending email to cgi-help@webwizarddesign.com ... PLEASE be specific about your error and include any server error messages / error codes and script output that you can when requesting help.
Please register the fact that you have downloaded and installed superfrm.pl by sending an email to superfrm@webwizarddesign.com. Why? So that when I update the script or release a security fix I can let you know that there is a new release :) ... that is the only thing I will use your email address for. I also want to get an idea of how many people are using the script for my own edification.
Please feel free to use the email link below to send me feedback on this script.
Enjoy,
Max
maxs@webwizarddesign.com