


GUESTNIK(1)					      GUESTNIK(1)


NAME
       guestnik - configurable guest book program

SYNOPSIS
	  <FORM METHOD=[POST|GET] ACTION="http://SERVER_NAME/cgi-bin/guestnik"
			 ENCTYPE="x-applictation-www-urlencoded">


DESCRIPTION
       The guestnik program accepts postings from various HTML
       forms.  It can reside as several links to the same script,
       and read a different configuration file for each link.  It
       is designed to be secure, using no user-supplied text to
       produce email addresses, never calling the UNIX/NT shell
       directly, and running with Perl taint checking.	It can be
       run by either Perl 4.036 or Perl 5.

       Options

       None, other than those in the configuration file.

       Configuration File Format

       The configuration file is scanned at program startup.
       There are three variable types -- simple (scalar)
       variables, arrays, and hashes.  The standard types are:

			   BlankError  hash
			   DateStyle   scalar
			   DeleteBlank scalar
			   Destination hash
			   FormatError hash
			   GetInfo     hash
			   Required    array
			   Standards   hash
			   Thanks      hash
			   ValidForm   hash
			   WhatInfo    hash
			   DEBUG       scalar

       The configuration file entries are like this:

	      Hash:	Name	key	value
	      Array:	Name	value1	[value 2 ...]
	      Scalar:	Name	value

       An entry must be on the first space of the line -- no
       indenting is allowed.  If a line begins with a space (or
       tab), it is assumed to be a continuation of the previous
       line.  Lines that are blank are skipped.	 Lines beginning
       with a # are comments, which are ignored.  The keys and
       names are not case-sensitive.

       The sample guestnik.cfg file gives an example of the



								1





GUESTNIK(1)					      GUESTNIK(1)


       format as it is used in practice.

       BlankError fieldname value
	   The message that you wish to send to the user if the
	   field is a required field, and is blank.  An example
	   would be:

	    blankerror name Your name was blank - please go
			    back and put it in the form.


       DateStyle [Europe|US]
	   Controls the order in which the day and month are
	   printed in the date.	 The default is US-style
	   MM/DD/YY; if you need European style DD/MM/YY put
	   europe in the field.

       DeleteBlank yes
	   If this parameter is defined, blank fields from the
	   form will not be included in the emailed output.

       Destination form <email address>
	   The place where the form is mailed to.  The form is
	   the 'form_type' specified in the HTML form.	Can
	   contain any number of addresses.  An example:

	    destination orderform  sales@company.com,accounting@company.com
	    destination registry   marketing@company.com,webmaster


       FormatError fieldname value
	   The message that you wish to send to the user if the
	   field is a required field, had a Standards entry, and
	   did not pass the Standards check. An example would be:

	    formaterror phone Your phone number didn't have enough numbers in it.


       GetInfo HTTP_VARIABLE yes
	   Fill this in if you wish to get information that may
	   be captured by the web server.  Examples of the common
	   ones are in the sample configuration file.  Here is
	   one that gets the browser used in the transaction:

	    GetInfo	   HTTP_USER_AGENT     yes


       Required field1 field2 [fieldn ...]
	   This is an array of field names which are required to
	   be filled out before the user is allowed to submit the
	   form.  If there is a corresponding Standards entry,
	   the field will also be checked to conform to it.  If
	   the checks fail, the BlankError and FormatError
	   entries will be checked to see if they exist, and that



								2





GUESTNIK(1)					      GUESTNIK(1)


	   message (or messages, in the case of multiple
	   failures) will be returned to the user along with a
	   polite request to go back and correct the problem.  A
	   default message is displayed if there are not
	   BlankError or FormatError messages. Example:

	     required name phone email company

	   This would require that the HTML form entries with the
	   names of name, phone, email, and company are not
	   blank.  They may be checked for format if a Standards
	   entry is present.

       Standards field	standard-spec
	   This is a format checking entry which takes the form
	   of a Perl regular expression.  A couple of standard
	   entries (phone numbers and email addresses) are
	   supplied in the sample configuration file -- contact
	   the author if you need a special one and are not
	   comfortable with regular expressions.  Here is the
	   example phone number check:

	       standards phone (\+?\d+[-/. ]\s*\d+|\d{7,})

	   Here is a standard that checks to see if a single-
	   letter answer is put in:

	       standards question1  ^\s*[ABCDabcd]\s*$

	   A small script called checkstd will test the Standards
	   entry for syntax, as well as test it against entries
	   that you make.

       ValidForm formname yes
	   This entry is checked to see if the hidden variable
	   named form_type matches.  If the form_type is not in
	   the configuration file, the user will not be allowed
	   to submit the entry.	 This is a check to make sure
	   that the right form is being submitted, and is used to
	   check the email destination address.	 IMPORTANT: This
	   must be filled in properly, and the form_type must
	   match.  To do this, just make sure that you have this
	   entry in your guestnik.cfg:

	       ValidForm  orderform  yes

	   And this as a line in your HTML form:

	       <INPUT TYPE="hidden" NAME="form_type" VALUE="orderform">


       Thanks formtype valid_html
	   This allows you to have a different thank-you message
	   for each form supported.  The valid_html entry can be



								3





GUESTNIK(1)					      GUESTNIK(1)


	   any valid HTML for display, and can span multiple
	   lines as long as each line begins with a space.
	   Example:

	       thanks orderform
		 <H1>Thanks for the Order!<H1>
		 <IMG SRC="/images/handshak.gif" ALT="Shake Hands Icon">
		 <P>
		 Thanks for placing an order with Internet Robotics.  We will
		 be sending a confirmation by return email or FAX as soon
		 as possible.<BR>
		 <A HREF="/index.html">Go to Home Page</A>

	   IMPORTANT: Note that the lines below the first begin
	   with a space.

       WhatInfo HTTP_VARIABLE description
	   Fill this in if you wish to have a description of the
	   information that may have been captured as a result of
	   the GotInfo directive.  It will be put in the mailed
	   form output.	 Example that matches the GetInfo entry
	   above:

		whatinfo   HTTP_USER_AGENT  The browser used by the customer


       Author

       Mike Heins, Internet Robotics, mikeh@iac.net




























								4


