Changes in Zot-Dispatch

This document describes the changes in Zot-Dispatch for version 2.0 and how to utilize them.

The source for Zot-Dispatch 2.0 can be found here.

Features added to Zot-Dispatch

Configuration File

Zot-Dispatch now has a configuration file. Nearly everything that needs to be configured can be done so in that file. Only the proper path to the perl interpreter must be changed in ZD's source. The configuration file must reside in the same directory as ZD and it must be called zd.conf.

Many of the new features of ZD described in this document are configurable in the configuration file. Read the configuration file document for information on how to configure Zot-Dispatch properly.

HTTP Template Retrieval

In Zot-Dispatch version 1.0 it was possible to place a template either inline in an HTML document, or in an external file readable by the server. Templates placed inline in the document were specified in a ZD-Method variable as "body:Template Body.....". If the template was placed in an external file the full pathname of that file was specified as "file:/dir/dir2/file".

Now in Zot-Dispatch you can also specify an HTTP URL as the location of the template. Simply place the full URL of the template document where you would normally put "body:Template Body....." or "file:/dir/dir2/file".

Example: 

    <INPUT type=hidden NAME="ZD-Method" 
        VALUE="ZD-Reflect;;http://www.oac.uci.edu/">
Protection Against Runaway ZDs

In order to save server resources Zot-Dispatch now spawns a child process which will sleep a predetermined (configurable) amount of time and upon awakening will kill the parent process if it is still running. If the parent process completes before the child awakens, the parent kills the child.

The amount of time that the child sleeps, in seconds, can be set in the configuration file. The default time is 120 seconds.

Mail and Append Limits

It is now possible to have ZD limit the amount of data that is appended or mailed. In the configuration file, the maximum number of characters to be appended or e-mailed can be set separately to allow protection against possible problems with appending or e-mailing unlimited amounts of data.

If the number of characters allowed is equal to zero (the default) then there is no limit.

Allowed Hosts

The hosts to which ZD can e-mail, and from which it can retrieve templates via HTTP can be limited separately in the configuration file.

Truncate E-mail Aliases

ZD can now be configured to chop off all characters after the "@" in e-mail addresses. Doing so will effectively limit all e-mail to users on the server machine. Truncating is turned off as the default.

E-mail Aliases

E-mail aliases can now be specified in Zot-Dispatch's configuration file. All e-mail addresses that ZD sends to are first checked against the alias list. If an alias exists for an address, the address is replaced with the alias.

Local Mail

If desired, ZD can be set in the configuration file to not allow mail sent to users on the server machine. This functionality is separate from the host limiting and truncating functionalities, and only stops e-mail addresses that do not have a host specified (which would go to the server machine).

The default is to allow local mail.

Append Files/Directories

The directories/files to which ZD is allowed to append can be specified in the configuration file. Entire directories, specific files, and filenames matching simple patterns can be specified as allowed or unallowed.

Notices of Errors

ZD 1.0 could send mail to form owners if an error occured with their form data and ZD. Now ZD can mail general errors that occur in ZD itself to a user specified in the configuration file.

Macro Variables

In ZD's configuration file collections of hidden variables (names and values) can be specified and associated with a single name. This name can be placed in the extra path information of a URL that accesses ZD (see example below). ZD will recognize the macro name and read in all of the associated hidden variables.

Macros variables are read in prior to reading any other variables entered in the form. Any other variables entered in through the regular form interface will act as though they came after the macro variables in the form, possibly overriding them.

If the user doesn't need to enter in any extra data to use your form, then ZD may be called from a standard HTML link without requiring a form or the button associated with it.

An example definition of a Macro Variable is: 

    <macro form1>
        ZD-Method = "ZD-Mail;lmegliol@uci.edu;"
        ZD-Method = "ZD-Reflect;;body:Thank You!"
    </macro>

An example of using this Macro Variable might be: 

    <FORM METHOD=POST ACTION="http://www.oac.uci.edu/cgi-bin/zd.cgi/form1">
        <INPUT TYPE=TEXT NAME="User-Name">
        <INPUT TYPE=TEXT NAME="User-Message">
        <INPUT TYPE=submit>
    </FORM>
In this case, most of the ugly Zot-Dispatch variables have been removed. Macro Variables can also be used to call Zot-Dispatch from a simple text link as opposed to a submit button (however, no user input will be available). For example: 
    <A HREF="http://www.oac.uci.edu/cgi-bin/zd.cgi/form2">
        Comment Form</A>
The comment link at the bottom of this page is an example of using a macro variable in this way. It dynamically creates a e-mail form specially tailored for the document it was referred to by.
Behavior of ZD when Sending E-mail
When ZD sends E-mail it handles each e-mail address in the following manner:
  1. If truncate is on, truncate the e-mail address.
  2. Check aliases for a match, if there is a match then replace e-mail address with alias & sends the mail (without further checking).
  3. If the address was not truncated, check to see if the host of the e-mail address is an allowed host. If not, then reject the address.
  4. If it is an address that was truncated or has no other host specified, then check to see if local mail is allowed. If not, then reject the e-mail address.
  5. If the address makes it to this point, then the mail is sent.
ZD will check each address it is given, compile a list of the addresses that have been allowed and then send the e-mail.
Direct Reflect
Up until now, the destination field (the second field) of ZD-Method variables went unused and ignored when the method was reflect. Zot-Dispatch now checks that field for the word direct. If anything other than this word is found, the behavior of ZD will be the same as before. If this word is found, however, one of the following will happen: If the template is a file, the contents of that file will be returned without substituting variable values into it. If the template is a body, the body will be returned without substituting variables into it (There is a problem doing it this way). If the template is a URL (a string that begins with http:, telnet:, ftp:, gopher:, news:, mailto:, nntp:, wais:, prospero:, cid:, or mid:), ZD will send back the Location: header redirecting the client to the URL. If the template does not fit any of these three, then the default response is returned. Problem: Because Zot-Dispatch does substitutions in the three fields of the ZD-Method variable, and then also does a substitution on the template, if your template is defined in the ZD-Method variable, then values may be substituted into the template during the first substitution. This will cause the ouput when using direct to not output the correct template source.
Dollar Signs In ZD-Method
If you want to include any dollar signs in any field of a ZD-Method value, you must include two consecutive dollar signs so that ZD will know you are not substituting a variable's value there.

This has been the method for templates also.

Destination Field Behavioral Changes
In the earlier versions of Zot-Dispatch, if a variable was to be substituted into the destination field, all values of that variable would be substituted. In the newest version of ZD, all values will be substituted provided that no other characters besides the variable are present in the destination field. If any other characters (even white space) are present, then only the last value of the variable will be substituted.

Examples: 

  <INPUT TYPE=text SIZE=40 NAME=addresses>
  <INPUT TYPE=hidden NAME=addresses VALUE="lmegliol@uci.edu">
  <INPUT TYPE=hidden NAME=ZD-Method
    VALUE="ZD-Mail;$addresses#;">
In this case, both values of addresses will be substituted into the destination field. 
  <INPUT TYPE=text SIZE=40 NAME=addresses>
  <INPUT TYPE=hidden NAME=addresses VALUE="lmegliol">
  <INPUT TYPE=hidden NAME=ZD-Method
    VALUE="ZD-Mail;$addresses#@uci.edu;">
In this case, only the last value of the variable would be substituted into the destination field.
That about sums up all the changes to ZD. Please send comments questions, suggestions, bugs, etc.
Leonard Megliola III
(Last Revised May 31, 1995)