Running ASForm Debug


Introduction

Quick: when was the last time you saw a CGI application that could tell you if it was properly configured, and explain what it's configuration parameters really mean? Consider yourself fortunate if you ever have. ASForm can. It was designed with ease of use in mind.

Once you have ASForm installed and at least running without our old friend Server Error 500, debug mode is there to help you out. It will tell you everything that can be known about how ASForm will behave, and will hopefully point you in the right direction toward a fix if things aren't quite right. There are only two things that should keep a running ASForm from showing you a screen like the one below, and those are when ASForm detects that it came from a file that is writable by the server, or when the master configuration is invalid due to a missing asformcfg: line. Unfortunately, in the second case, depending upon the file that got opened, you may or may not see an error message. As long as you're in there setting debug: on, make sure that asformcfg: exists.

There's one caution about configuration files: Make sure that the parameter debug: is the first paramater definition in the file, or it may not work right. If it's a named configuration that's acting like debug is somehow confused, you can always turn debug on in the default configuration then make a call to use the named configuration -- debug will spring back to life. It's better to just make sure that debug: comes right at the top of the parameter definitions when you're going to use it.

This document will explain to you what ASForm's debug mode does, and how to interpret anything it might bark about.

Special note for Internet Explorer users: Your browser thinks it's the smartest thing on the planet, but is not smart enough to read the HTTP headers that are sent to it. This is a problem for a lot of reasons, but in this case it means that your browser will ask you if you want to save the plain text that ASForm returns as its debug output. You can save it if you like, but you will probably find it more useful to you if you just go ahead and open it.

A Sample From My Working Installation

The sample below came from my working installation as I was preparing to write this, but some of the names have been changed to protect the innocent.

	=== Configuration of Art Sackett's asform.pl ===

	asform.pl version: 0.6(beta)
	Server Operating System: linux
	HTTP Server Software: Stronghold/2.4.1 Apache/1.3.3 C2NetEU/2409 (Unix) mod_perl/1.16 PHP/3.0.5
	Script URI: http://www.artsackett.com/cgi/asform.cgi
	Debug module path: asfmdbug.pl
	Debug run: Fri Feb 12 09:17:03 1999 GMT

	-------------------------------------
BASIC CONFIGURATION:


	Debugging invoked by default configuration.

--->	Script appears to be properly configured.

	-------------------------------------
ABUSE PREVENTION:

	Clients that do not send HTTP_REFERER will be rejected without
	any further testing.

	The following information from the server is used as the basis
	for referrer authentication (obtained by querying server):
	The server name is: www.artsackett.com
	The server name and the virtual host name are the same.

	HTTP_REFERER FILTERS:
	Checking referrer against www.artsackett.com only.
FYI:	This transaction matched.

	-------------------------------------
MAIL CONFIGURATION:
	SMTP (mail) host: mail.artsackett.com
	Testing mailhost and configuration...
	all recipients accepted by mail.artsackett.com

	Failure messages will be emailed to:
	"Art Sackett" <asackett@artsackett.com>
	Abuse reports will be sent.

	Multimail mode is ON.
	The following recipients will each receive mail from this form:

	asfresults: "ASForm Results" <asformresults@artsackett.com>

	Mail to webmaster and above recipients will appear to be from:
	"ASForm at artsackett.com" <asform@artsackett.com>

	Mail from script to above recipients will have the subject:
	ASForm Submission

	Undeliverable mail directory is configured to be
	asform/undelivered
***	asform/undelivered/undlvrd.asf does not exist.
	Trying to create it:  created successfully.

	And deleted it -- don't worry, it will be used.

	The last cleanup of orphaned undeliverable mail was done
	Thu Feb 11 19:34:55 1999

	There are no orphaned undeliverable messages.

	There are currently no recent undeliverable messages in
	temporary files.

	There are no undeliverable messages in the primary
	undeliverables file.


	-------------------------------------
AUTORESPONDER CONFIGURATION:
	Autoreponder is set to ON

	Reply message is configured to be asform/reply.txt which is:
		1) present on the filesystem;
		2) is a regular file (not a directory);
		3) is readable;
		4) is not empty (981 bytes);
		5) is a text file;
		6) contains asformreply:
	This file will be used.



	The subject of Autoresponder mail will be:
	Thank you for contacting artsackett.com!

	Mail from Autoresponder will appear to be from:
	"ASForm Autoresponder" <asform@artsackett.com>

	Echoing is OFF.

	-------------------------------------
DATA FORMATTING CONFIGURATION:

	The following form fields are required by this configuration:

		name: Your name
		email: Your email address

	Data will be sorted in the following order:

		name
		email
		message

	(Any data that is not mentioned in the sort order will be
	provided in the order it is received from the client.)

	Data for empty form fields will be suppressed.

	The following environment variables will be reported:
	REMOTE_ADDR (Currently: 216.17.134.222)

	Report is configured to be asform/report.txt which is:
		1) present on the filesystem;
		2) is a regular file (not a directory);
		3) is readable;
		4) is not empty (364 bytes);
		5) is a text file;
		6) contains asformreport:
	This file will be used.


	-------------------------------------
ERROR MESSAGE FORMATTING

	Error header is configured to be asform/errorhead.txt which is:
		1) present on the filesystem;
		2) is a regular file (not a directory);
		3) is readable;
		4) is not empty (1035 bytes);
		5) is a text file;
		6) contains <!-- asformdoc.*-->
	This file will be used.



	HTML formatting:
	Background color: #ffffff
	text color: #3300cc
	highlighted text color="#ff0000"
	link color: #0033ff
	vlink color: #0099ff
	alink color: #ff0000

	-------------------------------------
	Upon successful submission, client will be redirected to:
	http://www.artsackett.com/inprocess/new/thanks.html

	-------------------------------------
	DO NOT LEAVE DEBUGGING SET TO ON EXCEPT WHEN ACTIVELY 
	DEBUGGING YOUR INSTALLATION OR CONFIGURATION!!

	The script appears to be properly configured. The final test
	will be to thoroughly test it by putting it through it's paces
	online.

	Enjoy!


   

And that's what a good run looks like. Now we will dissect what it's telling us, in the same order as it appears above (which is the same order you will see in your installation, too).

The informational header

	=== Configuration of Art Sackett's asform.pl ===

	asform.pl version: 0.6(beta)
	Server Operating System: linux
	HTTP Server Software: Stronghold/2.4.1 Apache/1.3.3 C2NetEU/2409 (Unix) mod_perl/1.16 PHP/3.0.5
	Script URI: http://www.artsackett.com/cgi/asform.cgi
	Debug module path: asfmdbug.pl
	Debug run: Fri Feb 12 09:17:03 1999 GMT
    

This stuff probably won't matter much to you, but is pretty much self-explanatory. The main reason it is included is so that if you (or I) end up supporting ASForm for someone else, preferably for money ;-) we will know where the report came from. Notice that it's in plain text, suitable for emailing. The "Debug module path" tells where, in relation to ASForm, the file that creates the debug output lives. It's probably most handy to me, since I'm the guy most likely to have more than one debug utility installed.

If you keep copies of debug runs around, it'll be handy to know when it was run, and where.

Basic Configuration

	-------------------------------------
BASIC CONFIGURATION:


	Debugging invoked by default configuration.

--->	Script appears to be properly configured.
    

The first line tells us who invoked debugging -- with a bajillion configuration files on hand, was it a named configuration or the default? If it was a named configuration, you'd see something more like:

	Named configuration: "two" (file: asformcfg2.cfg).

	Debugging invoked by named configuration.
    

Kinda makes sense, huh? It tells you the alias of the named configuration, the file that the alias points to, and that debugging was invoked by the named configuration, in this case the indicated asformcfg2.cfg.

Notice that line that says "Script appears to be properly configured". That's what we're after. The arrow in the margin is to call your attention to things that you probably want to know about. Now, what if a warning had been generated that we need to know about?

	Script will function; the following warning was generated 
	while parsing the configuration file asformcfg.cfg:

???	1. Could not create and write asform/undelivered/undlvrd.asf.
   

Yep, ASForm will function, but possibly not in the way you want it to. Further down in the output, you'll find another arrow pointing out the reason for this warning (or another, if there is another warning). We'll get to that in a moment. In the Basic Configuration section, warnings are indicated by ??? in the left margin, and fatal errors by ===>. Later in the output, the "single arrow" ---> points to causes of errors, the "double arrow" ===> points to causes of fatal errors (if it's in the left margin, not the body), and three stars *** just call your attention to things like file system writes so you'll know they were attempted.

Abuse Prevention

	-------------------------------------
ABUSE PREVENTION:

	Clients that do not send HTTP_REFERER will be rejected without
	any further testing.

	The following information from the server is used as the basis
	for referrer authentication (obtained by querying server):
	The server name is: www.artsackett.com
	The server name and the virtual host name are the same.

	HTTP_REFERER FILTERS:
	Checking referrer against www.artsackett.com only.
FYI:	This transaction matched.
    

It's starting to make sense now, isn't it? That first indented line is just confirming for me that in my configuration file, I have pass no-referers: off. If it were on instead, "rejected" would be changed to "accepted".

The next block is informational and tell us what we already knew: the name of the server. If you're in a virtual host account, some will give up a name for the server, and another for your virtual host (in which case the filter is based upon the virtual host name). Since it's my domain, I only bother to check that the referrer was my domain. Had I gone further, we might have seen something more like this:

	www.artsackett.com/users/art
	artsackett.com/users/art
	artsackett.com/users/erin
	cgi.artsackett.com/users/art
	floogle.artsackett.com
    

Which lists, in the order referrers will be tested, all of the possible combinations that will allow a referrer to pass. (The protocol portion is not listed -- it can be any of http://, https://, or ftp://). Any referrer that does not match as far as the end of any filter will be rejected, period.

When you're in debugging mode, the filters are listed but not tested! It would be awfully hard to know why your filters are rejecting you if you couldn't get in to find out. That's why the FYI: in the margin. Had it not matched, we might have seen something like this:

FYI:	This transaction did not match!
	HTTP_REFERER: not provided by client
    

So we would have known why things were going wrong. This debug thing is pretty cool, huh?

Mail Configuration

	-------------------------------------
MAIL CONFIGURATION:
	SMTP (mail) host: mail.artsackett.com
	Testing mailhost and configuration...
	all recipients accepted by mail.artsackett.com

	Failure messages will be emailed to:
	"Art Sackett" <asackett@artsackett.com>
	Abuse reports will be sent.

	Multimail mode is ON.
	The following recipients will each receive mail from this form:

	asfresults: "ASForm Results" <asformresults@artsackett.com>

	Mail to webmaster and above recipients will appear to be from:
	"ASForm at artsackett.com" <asform@artsackett.com>

	Mail from script to above recipients will have the subject:
	ASForm Submission

	Undeliverable mail directory is configured to be
	asform/undelivered
***	asform/undelivered/undlvrd.asf does not exist.
	Trying to create it:  created successfully.

	And deleted it -- don't worry, it will be used.

	The last cleanup of orphaned undeliverable mail was done
	Thu Feb 11 19:34:55 1999

	There are no orphaned undeliverable messages.

	There are currently no recent undeliverable messages in
	temporary files.

	There are no undeliverable messages in the primary
	undeliverables file.
    

This section tells us about how we're going to get mail out to those recipients we've named. First we get told which SMTP server we're trying to use, then we try to contact it and verify that it likes all of the email addresses for recipients. If it doesn't like them now, it won't like them later, so we may as well fix whatever it complains about. I seriously doubt that ASForm will ever try to feed a rejected recipient address to an SMTP server, because it checks them first. But just in case, this is the smoke test.

It tells us the failure messages will go to the webmaster named in the configuration file, and that ASForm will send abuse reports if some bozo tries to pirate this copy of ASForm (or for any other reason, it sees a referrer that gets rejected by the filter, except rejections for those that don't provide HTTP_REFERER).

Then we get some pretty obvious stuff, like whether or not multimail mode is on, the list of recipients, the hidden from: address, and the subject that will be used -- that may have come from reply.txt.

Then the cool part, testing that we can write the primary undeliverables file. It doesn't exist because ASForm hasn't been unable to deliver any mail, or it has since managed to get it sent. So it goes out an creates the file, puts a couple of lines in it, reads it back, and then deletes it. Okay, so it didn't tell us that it wrote a couple of lines and read them back -- just trust me, it does.

But what if it failed for some reason? Glad you asked:

	Undeliverable mail directory is configured to be
	asform/undelivered
***	asform/undelivered/undlvrd.asf does not exist.
	Trying to create it: 
--->	No joy: No such file or directory.
    

As promised, it told us why, and put a "single arrow" in the margin. In this case, the directory undelivered did not exist -- you might get the same error if for some reason ASForm cannot create the file undlvrd.asf. The error message comes from the operating system, so it's as descriptive or not as the OS provides.

Then it tells us some stuff about undeliverable messages. It knows when it last checked for orphaned temporary undeliverable files because it leaves a note for itself on the file system, a file named cleanup. It reads the last-modified date of the file and tells us about it. If the file doesn't exist, it will tell us that, too:

	There is no record of when the last cleanup of
	orphaned undeliverable mail was done.
    

(If you ever want to force a cleanup, you can just delete the file cleanup and run ASForm in normal mode -- it'll do a cleanup right away.)

It then checks for "current" (less than an hour old) temporary undeliverable message files and tells us how many there are (if any), and then "orphaned" (over an hour old) temporary undeliverable message files. Finally, if there are any messages in the primary undeliverables file, it counts them and tells us about it.

Nuthin' to it.

Autoresponder Configuration

	-------------------------------------
AUTORESPONDER CONFIGURATION:
	Autoreponder is set to ON

	Reply message is configured to be asform/reply.txt which is:
		1) present on the filesystem;
		2) is a regular file (not a directory);
		3) is readable;
		4) is not empty (981 bytes);
		5) is a text file;
		6) contains asformreply:
	This file will be used.



	The subject of Autoresponder mail will be:
	Thank you for contacting artsackett.com!

	Mail from Autoresponder will appear to be from:
	"ASForm Autoresponder" <asform@artsackett.com>

	Echoing is OFF.
    

The first line is self-explanatory. It's either ON, OFF, or USER. Then we get into a file test -- this message is generated while it's being tested, so if it gets partway through before failing, you know what's right as well as what's wrong.

The subject in the Autoresponder message is reported, but we don't really know if it came from the configuration file or the reply file. Heck, if it's right, who cares?

The address the Autoresponder uses is that in public from:, which is reported here. Finally, debug tells us that our configuration file sets echo: off.

Data Formatting Configuration

	-------------------------------------
DATA FORMATTING CONFIGURATION:

	The following form fields are required by this configuration:

		name: Your name
		email: Your email address

	Data will be sorted in the following order:

		name
		email
		message

	(Any data that is not mentioned in the sort order will be
	provided in the order it is received from the client.)

	Data for empty form fields will be suppressed.

	The following environment variables will be reported:
	REMOTE_ADDR (Currently: 216.17.134.222)

	Report is configured to be asform/report.txt which is:
		1) present on the filesystem;
		2) is a regular file (not a directory);
		3) is readable;
		4) is not empty (364 bytes);
		5) is a text file;
		6) contains asformreport:
	This file will be used.
    

By now, you have this stuff wired, huh? In the required fields, we see the name used in our HTML form (if we got it right, anyway) and the "pretty words" that will appear in error messages if any of them aren't provided. Then we see the sort order, and a line that tells us that showall: off is in the configuration file.

Hey, look at that. It told us about the environment variables it captures, including the current value. Then a file test, just like the last one.

Error Message Formatting

	-------------------------------------
ERROR MESSAGE FORMATTING

	Error header is configured to be asform/errorhead.txt which is:
		1) present on the filesystem;
		2) is a regular file (not a directory);
		3) is readable;
		4) is not empty (1035 bytes);
		5) is a text file;
		6) contains <!-- asformdoc.*-->
	This file will be used.



	HTML formatting:
	Background color: #ffffff
	text color: #3300cc
	highlighted text color="#ff0000"
	link color: #0033ff
	vlink color: #0099ff
	alink color: #ff0000
    

Yep, another file test. Then a quick echo of what's in the configuration file for the stuff listed. If this configuration used error foot: it would have been tested and displayed right after error head:.

The Final Stuff

	-------------------------------------
	Upon successful submission, client will be redirected to:
	http://www.artsackett.com/inprocess/new/thanks.html

	-------------------------------------
	DO NOT LEAVE DEBUGGING SET TO ON EXCEPT WHEN ACTIVELY 
	DEBUGGING YOUR INSTALLATION OR CONFIGURATION!!

	The script appears to be properly configured. The final test
	will be to thoroughly test it by putting it through it's paces
	online.

	Enjoy!
    

Now we see the URL mentioned in the configuration file as the parameter success:. ASForm doesn't care if this is a valid URL or not. It rightly assumes that you can figure that out on your own ;-)

The line about not leaving debugging on is always there, and is good advice. ASForm's debug lays out a lot of information that even a novice cracker might be able to put to destructive use -- not to mention that it doesn't send any mail when it's in debug mode.

The last paragraph changes depending upon the warnings or fatal errors that come up. If there was a warning:

	This script may function as configured. Not all warnings are
	serious problems. If you are sure after reading the documentation
	that came with this script that you are satisfied with the way
	things are, you can probably safely ignore them.
    

In the example used, it's a pretty serious warning. If ASForm can't cache undeliverable mail, it's gone forever. It's not a fatal error because if the SMTP server is there and happy, you will get your form submissions.

Summary

Not a bad trick for a free CGI application, huh? If there's anything at all that will keep your running copy of ASForm from working in what it thinks is a proper fashion, it tells you about it. As I've often said, "in English as plain as possible". I guess that this can be a problem for those who don't speak English... if you speak another language fluently and would like to assist in teaching ASForm to speak another language, let me know. There's no money in doing it, but you will get credit for it somehow. Heck, if you're a web developer it could be good for your business. Or not. It kinda depends upon my reputation in those countries where the language is spoken, doesn't it?

I hope you enjoy putting ASForm to work, and that it does what you want done. That's why I allowed it to take over my life for a couple of weeks...

Enjoy!


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

 

© 1999 - Art Sackett