Superfrm: A flexible HTML form processor
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 four standard perl modules:
| Module | Purpose |
|---|---|
| CGI.pm | Shortcuts for HTML creation and form processing. |
| Net::SMTP | Easily send mail from within a perl script. |
| LWP::Simple | Lets perl script act as a simple HTML browser. |
| Sys::Hostname | Platform independent hostname function (for emailing) |
| VarSub | Module for doing variable substitution on templates (included with script in lib/ directory) |
If you know you have all of these modules installed, skip to step 2.
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.
All modules are required in order for the script to work properly. If you are not sure whether you have these or not, there are two ways to find out:
Verify your perl installation has the required modules with these commands:
perl -MNet::SMTP -e 1 perl -MLWP::Simple -e 1 perl -MSys::Hostname -e 1 perl -MCGI -e 1
If 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 shell
This 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.This is the easy part. First, open one of the sample configuration files included with this distribution (superfrm.* files under exmples/), configure it to match your server's needs, then copy it into the SAME directory as you copied the superfrm.pl script. Make SURE the name of it on the server is superfrm.cf. Now edit the superfrm.pl script. The first line of the script looks like this:
#!/usr/bin/perl
Change 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
Create a lib directory under your cgi-bin directory and copy the file lib/VarSub.pm into it. Make sure the permissions on the lib directory and the VarSub.pm directory allow the web server/script to read the files.
cd <directory where superfrm.pl is> # Unless the lib directory exists already mkdir lib cp <path to superfrm distribution>/lib/VarSub.pm lib/
Copy the default superfrm configuration file (into the cgi-bin directory where superfrm.pl now resides. Make SURE you read the section on configuring the superfrm.cf file and that you set any values you need to set in the file BEFORE using the script
cd <directory where superfrm.pl lives>. cp <path to superfrm distribution>/superfrm.cf ./ # Now READ the section below on configuration and set up the configuration file!
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:
If you set this to any value, security will be turned on; the script will only accept requests from servers that are listed in the ALLOW line and will also check for denied IP addresses in the DENIED_ADDRESSES directive.
Example: # This turns security on CHECK_CLIENT=1
This is a comma-separated list of servers and / or domains that are allowed to use this form processor. This variable allows you to limit who can use your script to process their forms. Machines may be listed by IP address or name, and the wildcard character `*' can be used to match partial names.
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
This is a list of comma-separated IP addresses or IP address patterns of clients not allowed to use this script.
Example: # No one from 192 network can use this and neither can 10.0.0.5 DENIED_ADDRESSES=192.*,10.0.0.5
This allows you to specify an artificial root directory (chroot environment) for the script to use when requesting template files using full path names. It is designed to let you keep outsiders from requesting sensitive files from your server. It is also useful if you keep your template files under a long path name.
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/
You may specify a mail host for the script to use ... if you do not, the script will default to using "localhost."
Example: # Our mail host is not local MAILHOST=mail.server.elsewhere.com
This specifies whether or not the script should log things like failed attempts to retrieve files, bad email addresses, and the names of servers that attempt to use the script but are not listed in the ALLOW list (if security is on). This file also contains info on the web clients (page used, browser type, host name) that use your forms.
Example:
# Turn on logging
LOGGING=1
You must specify the file the script should log to. The file you specify must be writable by the script.
# Log to superfrm.log n the current directory (default) LOGFILE=./superfrm.log
NOTE: 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.
Turning this on gives lots of detail about what the script is doing; it is useful for troubleshooting the script but should not be turned on unless you have lots of disk space or are working with webwizarddesign.com or another applications developer to debug the script.
Example: # No debugging DEBUG=
The name of the file to use for debugging; must be writable by the script.
Example: # Debug to /tmp DEBUGFILE=/tmp/superfrm.deb
See the example setup for example config files and templates.
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 :).
This field contains the email address of the user filling out the form. If you do not include this field in your form, the script will not be able to email the autoreply back to the user nor will it be able to tell you the email address of the person who filled out the form.
Example: Enter your email address: <INPUT TYPE=TEXT NAME="s.email" SIZE=30 MAXLENGTH=30>
This field is not required, but without it or the FIRST and LAST name fields you will not be able to use the user's first and last names in your templates. If you do specify this field in your form, superfrm.pl will put the user's first and last names in the variables $first and $last (if they are available) for you to use in your templates (See Using Variables in Templates below.)
Example: Enter your FULL name: <INPUT TYPE=TEXT NAME="s.fullname" SIZE=50 MAXLENGTH=50>
The first name of the user filling out the form. This field is not required, but you will not be able to use the user's first name in your templates if both this field and FULLNAME are missing.
Example: Enter your first name: <INPUT TYPE=TEXT NAME="s.first" SIZE=40 MAXLENGTH=40>
The last name of the user filling out the form. This field is not required, but you will not be able to use the user's last name in your templates if both this field and FULLNAME are missing.
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 templates 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.':
Do not send email output of the form to the user specified in S.MAILTO. If this option is not present or is blank, the script WILL send an email of the form output to the user specified in S.MAILTO.
Example: <!-- Don't send an email of the form output in this form --> <INPUT TYPE=HIDDEN NAME="S.NOMAIL" VALUE=1>
Do not send an autoreply to the user specified in the S.EMAIL form field. If this option is not present or is blank, the script WILL try to send an autoreply to the user specified in the S.EMAIL field of the form.
Example: <!-- Don't send an autoreply in this form --> <INPUT TYPE=HIDDEN NAME="S.NOREPLY" VALUE=1>
Email address of the user who receives the output of the form. If this field is blank, no email will be sent.
Example: <!-- Email the form output to this person --> <INPUT TYPE=HIDDEN NAME="S.MAILTO" VALUE="nobody@noserver.net">
A comma-separated list of required fields. If any of these forms are missing from the submitted form, an error page will be shown to the user (default or page specified in S.ERRORPAGE).
If you wish, you can optionally add a label to be displayed for each field that is missing ... in the form of real_field_name:label
Example: <!-- These fields must all be filled out --> <INPUT TYPE=HIDDEN NAME="S.REQFIELDS" VALUE="EMAIL,FIRST,SHIRTSIZE"> <!-- These fields must all be filled out ... and we want nice display values for them--> <INPUT TYPE=HIDDEN NAME="S.REQFIELDS" VALUE="EMAIL:Email Address,FIRST:First name,SHIRTSIZE:Shirt size">
What email address should the autoreply and emailed form appear to come from? if none is specifed, a default will be used.
Example: <!-- Email from this form should come from here --> <INPUT TYPE=HIDDEN NAmE="S.MAILFROM" VALUE="me@mehost.com">
If set to any value, this field tells superfrm.pl to send the form output to the person given in S.MAILTO using the name and email address of the person submitting the form. This field is optional.
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.
The email form that will be sent to you with the form's output.
Example: <!-- Use the form on our sister site as an email template --> <INPUT TYPE=HIDDEN NAME="S.MAILFORM" VALUE="http://sistersite.com/mailform.txt">
The email form that will be sent to the user filling out the form AFTER he / she successfully fills out your form.
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">
The HTML page that will be shown to the user if she / he forgets to fill out a required field (field listed in S.REQFIELDS variable).
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">
The HTML page that will be shown to the user after he / she successfully fills out and submits the form.
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 :)!
The following variables are available for use in all forms:
| Name | Description |
|---|---|
| $first | First name of user (if given) from field in form named S.FIRST or S.FULLNAME. |
| $last | Last name of user (if given) from field in form named S.LAST or S.FULLNAME. |
| $fullname | Full name of user ... this will be a combination of the S.FIRST and S.LAST fields if those were given or the output of the field named S.FULLNAME if that field was given. |
| Email address of the user filling out the form (if given from field in form named S.EMAIL. | |
| $remote_addr | Address of the host the user is connecting from (if given) as reported by the user's browser. |
| $remote_user | Username of the remote user as reported by the user's browser; rarely present. |
| $remote_host | Host name of the browser's remote host ... rarely given, $remote_addr more reliable. |
| $date | Date / time the form was processed .. I.E. Thu Apr 1 00:20:22 GMT 1999 |
| $field_list | List of required fields the user did not fill out. Only available in the S.ERRORPAGE form. |
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}Example: In the error page, we want to use the user's first name if it is present in the submitted form or a generic greeting if it is not in the form.
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 example setup for
a sample input form, templates, and configuration you can use to help
you get started.
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