Configuring ASForm

Introduction

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 cgistuff@artsackett.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 http://www.artsackett.com/grey_papers/cgi/broken_install.html for some hints, tips, and what to do if and when things go wrong.

Required Parameters

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 configuration file(s).

Parameters within the perl script:

  1. 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:

    #!/usr/bin/perl

    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.)

     

  2. 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.

     

  3. 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.

  1. 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 back.

     

  2. 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.

     

  3. public from: user@yourisp.com "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.

     

  4. webmaster: user@yourisp.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.

     

  5. recipients: alias: user@yourisp.com "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 recipients:

    mailfile: path/filename
    datafile: path/filename

    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.

     

  6. 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.

  1. 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 it out.

     

  2. 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.

     

  3. 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.

    Global settings:

    Narrowing the filter:

    An example:

    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.

     

  4. 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.)

     

  5. 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.

     

  6. 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 head.

     

  7. 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.

     

  8. 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.

     

  9. bgcolor:
    text color:
    link:
    alink:
    vlink:
    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.

     

  10. highlight: ff0000
    The font color used to call attention to key points in the error messages. Like those above, use no quotation marks or #.

     

  11. 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 address)
    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 be submitted.

     

  12. 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 ordering.

     

  13. 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.

     

  14. 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.)

     

  15. 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".

     

  16. 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.

     

  17. 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).

     

  18. 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 from echo.

     

  19. report: path/filename
    As for replymsg, but is the report sent to recipients, and must contain the line asformreport: on a line by itself.

     

  20. hidden from: user@yourisp.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.

     

  21. 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.

     

  22. 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.

     

  23. 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.

     

  24. 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.

Index
[online]		 Introduction/
Features		 Configuration Installation
 
Customizing
Error Messages		 Writing
Message Templates		 Writing Forms for
Use With ASForm		 Running
ASForm Debug

 

© 1999 - Art Sackett