Please do not try to deploy ASForm without first having carefully
read and understood the documentation! ASForm is a highly configurable
application, and to blindly push ahead without knowing what you are doing
is sure to be a frustrating experience.
At this point, you should have read the description of ASForm's features
and should have a pretty good idea of how you want ASForm to behave. If
you have done so, you should find the configuration of ASForm to be
pretty straightforward. There are quite a number of configuration
parameters, but they're all simple to understand and configure -- most
of them are optional.
Configuration files are just plain text, with the rule being that a
"newline" (the Enter key on your keyboard) terminates the
definition of the configuration parameter. If your text editor likes
to add newlines for you, you'll have to either disable that behavior
or work around it when creating a configuration file. Embedded comments
are allowed -- everything on a line after a # is taken to
be a comment, except when it's used in the URL of sucess: and
indicates a document anchor. Empty lines are ignored.
When an email address is used in a configuration file, it must be
formatted properly, as user@yourISP.com "email alias" with
the email alias always being optional. For example, my address might
be email@example.com "Art Sackett's CGI Stuff".
If you are inexperienced in setting up CGI applications, you may want
to read through the artsackett.com grey paper
some hints, tips, and what to do if and when things go wrong.
ASform will not run at all without some required parameters defined.
two of these are in the perl script itself, the others are in the
Parameters within the perl script:
- The path to the perl interpreter:
The very first line of asform.cgi must indicate
the proper path to the perl interpreter on the target system.
In many cases, this will be /usr/bin/perl which is the
default in the distribution copy of asform.cgi. This line must
be in the form:
with the shebang (#!) in place in the
first two character positions of the very first line.
(If you don't know what the path to the perl interpreter is,
and you aren't sure how to find out, please read through the
artsackett.com grey paper mentioned above.)
- The path to the default configuration file:
If you are okay with the default configuration file being
in the same directory as asform.cgi and named asformcfg.cfg
you do not need to change this. The line that you define this
parameter on is line 61, and looks like this:
$config_file = 'asformcfg.cfg';
It's easy enough to spot, and is in a section that is commented
as being USER CONFIGURATION.
- IMPORTANT NOTE:
After uploading ASForm to your server, make sure that
it is NOT writable by the server. If it is, it will know and
it will absolutely refuse to do anything but bark an error at whoever tries
to use it. Even in debug mode, all it will do is bark an error and refuse
to complete the debug run.
Parameters that must be in every configuration file:
There's nothing saying that you have to use the provided example
configuration file as a template -- but it might be easier unless
and until you've made several of them.
- asformcfg: has to be somewhere within the
configuration file on a line by itself. This is what tells
ASForm that this is a configuration file. Without it, ASForm
will bark at you -- and if it's your default configuration
file, even running ASForm in debug mode won't tell you that
this is what's wrong. All you'll get is the Fatal Error page
- mailhost: mail.yourisp.com
This line must be present, and tells ASForm the name of the
SMTP (mail) server to talk to for sending mail. Chances are
that somewhere in your computer, possibly in your email client
configuration, you have the name of the SMTP server configured.
This is probably the one you want to identify here. (It is the
server to which you send your outbound mail.) There must
be only one of these lines in your configuration file.
- public from: firstname.lastname@example.org "email alias"
This is the address that ASForm will use publicly, as when
sending Autoresponder mail. It should be a valid email address,
even if not your primary mail account. This way, if an email
message is bounced, it has somewhere to bounce to. Some
SMTP servers will refuse to talk to ASForm if the value you
provide here is not known to it. There must be only one of these
in your configuration file. If public from holds a
malformed email address, ASForm will not accept form submissions,
and will give users an error message.
- webmaster: email@example.com "email alias"
This is the address to which Fatal Error Reports, Abuse Reports,
and otherwise undeliverable mail will go. This, too, should be
a valid email address so those important messages will be sent
to a real person. This address is not exposed to the web. You
can name as many webmasters as you choose to; if they appear on
the same line, separate the entries with a comma. You may also
use several webmaster: lines in the same configuration,
each with one or several recipients per line. The email address(es)
used here must be properly formed, or ASForm will not accept form
submissions and will return error messages to users.
- recipients: alias: firstname.lastname@example.org "email alias"
This identifies the possible recipients for submission reports
from ASForm. The alias is required, but is only used
if you don't use multimail mode, so your HTML form can
specify who should receive the submission report. If multimail
mode is not enabled and your HTML form doesn't specify who should
receive the submission report, only the first named recipient will
receive a report. Your HTML form can specify any number of
recipients -- as long as the alias exists, mail will be sent to
each recipient whose alias is sent by your HTML form. (At this time,
the email alias doesn't matter -- ASForm doesn't write a To:
line, so everybody gets the equivalent of a bcc, a
"blind carbon copy".) These email addresses must be properly formed,
as mentioned above.
If you wish to write files for every form submission, there are
two types of files available to you: mailfile and datafile,
and you may have one of each specified. A mailfile is nothing more than
a file to which all form submission reports are appended -- it can grow
quite large very quickly if your form is heavily used, so you should
keep an eye on it and empty it from time to time. A datafile is meant
to be used in conjunction with some other software that knows how to
deal with comma-separated (or "delimited") flat-file database tables. In
a datafile, embedded commas within the data are escaped with "backslashes",
HTTP environment variables that are captured are appended to the end of
the record, and it's all followed by the time string indicating the time
at which the form was processed. To add a mailfile or datafile to your
The specified file does not have to exist, but it must be a file that
ASForm can create. If it exists, it must be writable by ASForm. If one
of these files is specified but does not exist, it will be created when it
is needed, or when ASForm is run in debug mode.
Special note for datafiles: If you wish to use ASForm in this
manner, you should also include every field your form can send in the
sort order -- or your database table will very likely become worthless to
you very soon.
- success: http://www.yourisp.com/user/thanks.html
This is the URL to which to redirect users after a successful form
submission. It must be a complete URL, including the protocol
portion (http://). ASForm doesn't know or care if this is
a valid URL -- 404's are your problem ;-) This is the one place where
using a # is not necessarily a comment. If you form
the URL such that it looks like a document anchor is on the end of it,
ASForm will know that it's a document anchor. You can, however, include
a comment on this line if you are sure to leave at least one space
between the end of the URL and the start of the comment.
Optional Stuff (that might still be very important):
None of the rest of the configuration variables are absolutely
essential, but a couple of them are very important to know about.
Whether or not you use them is your choice. The very important ones
are listed first.
- undelivered: path/to/directory
This is the path to a directory in which ASForm will store
undelivered mail. (ASForm never stores autoresponder mail -- it
either goes or it doesn't.) This directory must be created by you,
since ASForm will not make directories. ASForm has to be able to
write files in this directory -- if it's possible on your server,
you should create the directory such that the user the server runs
as is the owner. Also, note that in this beta release, ASForm doesn't
traverse upward in the directory structure with ../../ notation.
If you want to place this directory such that it's "upward" from the
installed location of ASForm, you have to provide the full path name.
(e.g. /users/you/www/asform/undeliverable) It doesn't really
matter if you include the trailing slash or not -- ASForm will figure
- debug: on|off
This is the debug flag, which accepts on as the argument to
turn debugging on, and anything else or nothing at all to turn it off.
If you skipped past the description of debugging mode, you really
should read it now. It's a very useful tool, and one that you won't
find in many other free CGI applications.
- referers filter: (see below)
The referers filter is used to keep other sites from pirating
(or trying to pirate) your installation of ASForm. Unlike some other form
processors, ASForm is pretty much useless to a pirate, because it does
not accept email addresses for recipients from the web (with the exception
of the Autoresponder recipient address, anyway). This being the case, if
someone manages to feed data to ASForm, at least one of your intended
recipients will receive it. The strange results should raise alarm bells.
The referrers filter compares the value of the HTTP environment variable
HTTP_REFERER to the filtering rules you provide to determine
whether or not to continue processing. If the value of HTTP_REFERER does
not match against your filter, the transaction is aborted and the user is
presented with an explanatory HTML document. Whether to pass or reject those
clients that do not set this variable is determined by the value of the
configuration variable pass no-referers. With the referrers filter,
you can determine which hosts and which directories within each host are
acceptable to you.
The referrers filters are applied in sequence, from the first one in the
configuration file to the last. Filters can be grouped on one line, or
spread across several lines, or a combination of the two styles.
Changes the current host name to (host) for the next
filter listed. If your referrers might come from a host other
than the one that ASForm is installed on, for instance
http://www.yourisp.com while your script is installed at
http://cgi.yourisp.com, you tell ASForm that it should
accept referrers from www by setting the filter:
referers filter: +host(www)
This entry will affect all subsequent filters unless and until you
change the host name again.
Tells ASForm to accept all referrers from that host.
You cannot further narrow this filter into directories -- any
referrer from this new host passes.
Strips the host name. If you want referrers from, say
http://yourisp.com to pass, and ASForm is installed at,
say, http://www.yourisp.com, --host will
do the trick. This filter can be narrowed further, and if you
want all referrers from the stripped host domain to pass,
it must be the last filter mentioned in the configuration.
Disables all filtering, no matter where in the configuration it
appears. Probably not a good idea.
Narrowing the filter:
- referers filter: users/you/here, users/you/there
By specifying a path here, you can restrict referrers to those that
came from within the directory(ies) specified. The filter stops at
the point where you end your filter name -- as long as the URL of
the referer matches as far as the end of your filter, it's considered
a match. You can go so far as to name an individual document, as
well. users/you/directory/document.html ought to end with
only one document referrer able to invoke ASForm, unless you have
named a directory document.html. Do not use a leading
slash in your filters!
Running ASForm in debug mode will show you how your filters will
be applied, so if you're not sure that you got it right, try running
debug. Just don't forget to switch it back off as soon as you're done.
Assuming ASForm is installed on www.yourisp.com:
referers filter: +host(floogle)
referers filter: ~jdoe/forms, ~jdoe/misc
With the first line, we change the host name to floogle, so
it's now floogle.yourisp.com. Because we never mention
www, any value of HTTP_REFERER from www.yourisp.com
is rejected, even if it's http://www.yourisp.com/~jdoe/index.html.
On the second line, we narrow the filter to two directories, and two
directories only. If you're operating from a user account at an ISP,
you probably want to go at least as far as that portion of the URL that
indicates your own account. In this case, any value of HTTP_REFERER that
begins with http://floogle.yourisp.com/~jdoe/forms or
http://floogle.yourisp.com/~jdoe/misc will pass, and all others
will be rejected.
Important note: The protocol portion of the URL must be one of
http://, https://, or ftp://. ASForm isn't
intended to be used with any other protocol.
VERY Important note: If you are working with a secure server (https
protocol), you must use the POST request method from your
form(s). ASForm won't let you do anything so foolish as a GET in HTTPS.
For the curious: Yes, I use two different spellings of "referrer".
In the HTTP environment variable, it is misspelled as referer, and
this is how ASForm uses it, just for the sake of remaining true to convention.
In these documents, I use the proper spelling to refer to the concept, and
the conventional one to refer to the implementation.
- pass no-referers: on|off
As briefly mentioned above, this controls whether to globally accept
or reject those transactions that don't come with the environment
variable HTTP_REFERER set. If not specified, it defaults to ON, which
means that if HTTP_REFERER is not sent, the client passes. There may
be a browser about that doesn't set this variable, and
pass no-referers: on will let them in. Setting this to off
will block those who don't send HTTP_REFERER (as some spambots don't, but
that shouldn't be an issue here) and explain why. It will also refer
the user to a page at www.artsackett.com that will indicate to them
whether or not their browser sets this variable, and explain why it is
that they were rejected. (This will be true after I get that page and
the corresponding CGI app written, anyway.)
- abuse reports: on|off
Abuse reports are switched on or off here, and default to ON if you
don't explicitly turn them off. If a transaction is aborted because
HTTP_REFERER was rejected by your filter, a report of the incident can
be mailed to the person(s) identified in your configuration as
webmaster. ASForm is not very abusable anyway, but this way
you will know if someone tries. (Abuse reports are not sent for cases
where no HTTP_REFERER is sent, only those where it is blocked by the
filter.) Set to off to disable abuse reporting, on
(or anything else, for that matter) to enable.
- error head: path/filename
This identifies the "header" that will be used in error messages
returned to the user. It should be an HTML snippet, and it will be
placed between the <body> tag and the error message generated
by ASForm. Please remember when specifying paths in URLs, the path
is relative to the URL of ASForm, not that of the referring document.
The error message is placed in a table with its width set to 65%, so
if you want to narrow it, embed that table within one opened in error
- error foot: path/filename
Like error head, but placed after the error message, above
</body>. If you used a table to narrow the error message, be
sure to close it here.
Note: Don't try to use Server Side Includes in your
error head and error foot documents. They wouldn't
work anyway, and just to be safe, ASForm strips out anything that might
be an SSI directive before serving up the document.
- background: path/filename
The background image, if any, used in error message HTML. It ends up
in the <body> tag, as you would expect. Do not use any
quotation marks here, though -- ASForm will put them in.
RGB values to be used in the <body> tag, just as you would expect.
Again, use no quotation marks, and don't use the # which
would be interpreted as a comment delimiter. If not specified, the
bgcolor defaults to white (#ffffff) and the others just aren't mentioned.
- highlight: ff0000
The font color used to call attention to key points in the error messages.
Like those above, use no quotation marks or #.
- required: field name "pretty words"
This is where you specify which of the fields in your form must
be filled in -- if they're not, the user gets a nice error message
complete with the formatting you just defined. Make sure that the field(s)
exist or your users will never be able to submit a form. The pretty
words are what get used in the error message telling the user what
they didn't provide. Have you ever filled out a form, only to be told that
you didn't provide the information 'add1csz' or something even more cryptic?
With ASForm, you can decide what the user is presented with. To go with the
example just presented, "The city, state, and ZIP code for the delivery
address" is a lot easier. To make that happen:
required: add1csz (The city, state, and ZIP code for the delivery
will do this nice thing for your visitors. If you don't include pretty words,
your users will get "add1csz".
Field names are case sensitive -- if you get complaints that no one can
submit your form, check this while running debug.
NOTE: If your form contains any fields whose names begin with
email or hide_email, they will automagically become
required, and will be checked for proper formation before the form can
- sort order: field name, field name, field name
The order into which to sort returned data, applies both to the raw
data dumps (if you use them) and to the ordering of the data in the
datafile (if you use one). Also case-sensitive, but if you
name a field that doesn't exist or is null, it doesn't break anything.
In the datafile, null data is represented by an empty entry. Any data
that does not appear in the sort order will appear in raw data dumps
after sorted data, and in the order it was received from the client
(which is usually, but not guaranteed to be, the order in which it
appears in your HTML form).
NOTE: Moving an environment variable such as REMOTE_ADDR into
the sort order makes it a part of all data dumps, so if echo is
set to on, the Autoresponder will include that environment variable in
the echo. There is a workaround for this described elsewhere in the section
on creating HTML forms for ASForm.
Very Important Note: If you're using a datafile, you should
include all of the data that your forms might send in your sort order. If
you don't, your tables will almost certainly get trashed by random data
- showall: on|off
Setting showall to on causes empty fields to be represented in
your raw data dumps -- otherwise, those fields without an entry will be
suppressed. This field has no effect on the writing of a datafile.
- environment: HTTP environment variable(s)
A list of HTTP environment variables such as HTTP_REFERER, REMOTE_ADDR,
HTTP_USER_AGENT, etc. that you wish to capture from each transaction.
They will be included in your raw data dumps, in your datafile, and can
be used in submission reports and/or Autoresponder replies. As noted
above, if one of these environment variables ends up in your sort order,
it will appear in Autoresponder messages if echo is on. (If not
listed in sort order, HTTP environment variables are tacked onto
the end of datafiles in the order they are listed in your configuration
file, right before the time string.)
- multimail: on|off
With multimail set to on, all recipients named in your
configuration file will receive all form submission reports. Otherwise,
only those specified by your HTML form will be mailed, as noted above
in item (5) of "Required Parameters".
- autorespond: on|user|off
Sets the Autoresponder to on, user mode, or off. If on, whenever a form
is submitted and there was a field named email in your HTML
form, the address indicated in email will be sent a confirmation,
that may be one you have provided and indicated in replymsg:.
When set to user mode, whether or not the autoreply is sent is determined
by your HTML form, either by giving the user the choice or by using a
hidden input. To enable the Autoresponder in user mode, your form must
send the field named autorespond with the value on. Off,
of course, disables the Autoresponder.
- replymsg: path/filename
If you choose to use one, this is the file that will be used as the
Autoresponder reply message, which may be a template as described in the
section "Writing Report and Autoresponder Messages and Templates". If you
specify a file here, it must be readable by ASForm, it must not be empty,
and it must contain on a line all by itself asformreply: (that
will be stripped when this file is parsed).
- echo: on|off
With echo set to on, a raw data dump will be appended to the
bottom of Autoresponder messages. As noted elsewhere, any HTTP environment
variables you capture that are in your sort order will also appear in the
echo, unless you use a workaround. Any fields that your form uses whose
names (not values!) are prepended with hide_ will be hidden
- report: path/filename
As for replymsg, but is the report sent to recipients, and must
contain the line asformreport: on a line by itself.
- hidden from: email@example.com "email alias"
This is an email address used as a From address when ASForm sends mail
to recipients and webmasters. This feature is mainly intended for use
with email sorting filters. If this is not specified, public from
will be used instead.
- subject: Your subject here
This is the subject to be used in submission reports. It may be overridden
by a report template. Again, for details please see "Writing Report and
Autoresponder Messages and Templates" for details.
- timezone: gmt|local
ASForm defaults to using GMT as the time wherever it uses the time, with
this variable you can change it to local time ("local" being the local time
of the server, not necessarily that in which you live). If set to local,
wherever the time is used it will be appended with (server local time)
-- if you use GMT, it will be appended with GMT.
- altconfig: (alias) path/filename
In a default configuration file, specifies the alias of a "named
configuration" and the path to the actual file. In a named configuration
file, altconfig is ignored. To use named configurations, your
HTML form must pass a field named config with the value of a
valid alias. If config comes along with an invalid alias, it's
error message time. You can use as few or as many named configurations
as you care to write, and they can be grouped on one line, or across
several (as long as each new line starts with altconfig:), or
in any combination of the two styles.
- FINALLY: If you're using the example configuration file, comment
out the last line that reads You must configure this script!. If
you don't, ASForm will not run. Anything that appears in a configuration
file that is not one of the parameters mentioned above and is not commented
out is all the excuse ASForm needs to refuse to work for you. I did this on
purpose -- if something odd happens that causes a configuration file to
become corrupted, ASForm just refuses to use it. This keeps really strange
things from happening.
© 1999 - Art Sackett