The configuration file must reside in the same directory as Zot-Dispatch and
must be called zd.conf. It is possible to change the location
and name of Zot-Dispatch's configuration file, but it must be done in the
source code for Zot-Dispatch (It's right at the beginning of the source).
All blanks lines and lines that begin with a pound sign ("#") are ignored. An entry in the configuration file is either a single line, such as
TRUNCATE offor a block of lines, such as
<ALIASES>
juser joeuser@someplace.net
</ALIASES>
Zot-Dispatch will time-out if it has not completed reading the configuration
file after 120 seconds.
To set the amount of time before ZD's child kills it use the
"KILL_TIME seconds" directive, where seconds is the
number of seconds before ZD's child awakens and kills ZD.
For example:
KILL_TIME 120
This example sets ZD's child to sleep two minutes before waking and killing ZD.
To set the e-mail address to which general errors with ZD will be sent, use
the "ERRORS_TO address" directive, where address is
the address of the person to recieve the e-mail.
For example:
ERRORS_TO lmegliol@uci.edu
Multiple addresses separated by commas may be used.
To set the directory in which libwww-perl may be found use the directive
"LIBWWW_PERL path" where path is the directory
that contains libwww-perl.
For example:
LIBWWW_PERL /Web/libwww-perl
Not setting the location of libwww_perl will make it impossible to retrieve
templates via HTTP.
To set the directory in which cgi-lib.pl may be found use the directive
"CGILIB path" where path is the directory
that contains cgi-lib.pl.
For example:
CGILIB /Web/cgi-bin
If the value of CGILIB is not set Zot-Dispatch will not work
correctly.
To set the directory that the hostname program resides in use the
"HOSTNAME_PATH path" directive, where path is the
directory in which the program resides.
For example:
HOSTNAME_PATH /usr/ucb
To set the location of the program sendmail, use the
"MAIL location" directive, where location is the
exact location of the program.
For example:
MAIL /usr/lib/sendmail
To set the location of the program date, use the
"DATE location" directive, where location is the
exact location of the program.
For example:
DATE /usr/bin/date
The date program specified must work using the syntax:
date_program [+format]
The block used to configure the hosts from which documents may be retrieved
via HTTP begins with a <HTTP_HOSTS> tag. Three types of
directives can follow this tag:
order
order directive can have the values
"deny,allow",
"allow,deny", or
"mutual-failure". The value
of this directive determines the order that Zot-Dispatch
evaluates the deny and allow directives. Only the last
order directive is accepted.
deny,allow
allow,deny
mutual-failure
order is
deny,allow.
allow
allow all" is used, all hosts will be allowed.
deny
deny all" is used, all hosts will be denied.
For Example:
<HTTP_HOSTS>
order deny,allow
deny .gov
deny .com
deny all
allow .uci.edu
</HTTP_HOSTS>
In this example the order directive is "deny,allow",
so the deny directives will be evaluated first.
In this case any hosts with ".gov" or ".com" in their name will be denied,
but this example is actually redundant. The "deny all"
directive will not allow documents to be retrieved from any hosts, so the
"deny .gov" and "deny .com" directives are not needed.
After evaluating the deny directive, ZD will check the
allow directives. In this case anything with ".uci.edu" can be
accessed via HTTP.
This block works and is used exactly the same as the
Allowed HTTP Hosts described above, except
it begins with the <MAIL_HOSTS> tag and ends with the
</MAIL_HOSTS> tag.
The e-mail alias block in the configuration file begins with the the tag
<ALIASES>. On each successive line in the e-mail alias block
file there must be either a blank or comment line, or an alias followed by the
e-mail address to which the mail should be sent. The alias block
should be closed with the tag </ALIASES>.
Example:
<ALIASES>
juser joeuser@someplace.somewhere
web webmaster@localhost
# Comment line.
</ALIASES>
To set Zot-Dispatch to truncate all e-mail addresses after the "@", use the following in your configuration file:
TRUNCATE on
To turn it off, use:
TRUNCATE off
If you want to allow mail to be sent to the local machine, use the directive:
LOCAL_MAIL enabled
If you do not want mail to be sent to the local machine use:
LOCAL_MAIL disabled
To set the number of characters that ZD is limited to appending and e-mailing
use the "APPEND_LIMIT limit" and
"MAIL_LIMIT limit" directives, respectively, where
limit is the maximum number of characters allowed.
All data will be truncated at limit characters before e-mailing and appending. Setting limit to zero will disable limiting.
For example:
MAIL_LIMIT 5000
APPEND_LIMIT 0
In this example e-mail will be limited to 5000 characters and appending will be
unlimited.
The block used to specify which files may be appended to begins with the tag
<APPEND_FILES> and ends with the tag
</APPEND_FILES>.
Each line in the block must have the full path/filename of the file(s) that
is/are allowed. It is possible to use the wildcards "?" and
"*" in the filenames to specify groups of files or entire
directories.
For example:
<APPEND_FILES>
/Web/doc/indiv/lmegliol/append.file
/Web/doc/indiv/lmegliol/append-dir/*
/Web/doc/indiv/lmegliol/cgi-bin/.append-??
</APPEND_FILES>
In this example, ZD would be allowed to append to the file
/Web/doc/indiv/lmegliol/append.file, any of the files in the
directory /Web/doc/indiv/lmegliol/append-dir/, or any of the
files in the /Web/doc/indiv/lmegliol/cgi-bin/ directory that match
the pattern .append-??.
Beware when using the "*" wildcard as is done in the example
above, because all subdirectories of
/Web/doc/indiv/lmegliol/append-dir/ will be allowed appending.
Only those programs that are registered with Zot-Dispatch as filter programs
in the configuration file can be used to filter data through before dispatching.
The proper way to specify these programs is using the
<FILTER_PROGRAMS> block.
<FILTER_PROGRAMS>
Symbolic Name = "Absolute Path To Program"
</FILTER_PROGRAMS>
Where Symbolic Name is the name associated with the listed program and
placed in the ZD-Method to instruct Zot-Dispatch to perform the
filtering, and Absolute Path To Program is the absolute path to the
program that will be executed. Any command line options that must be
given to the program at runtime can be placed within the double quotes as
follows:
<FILTER_PROGRAMS>
fmt = "/usr/ucb/fmt -80"
</FILTER_PROGRAMS>
All programs specified must take their input from the STDIN. Any output to
STDOUT will be considered the new reponse data to be dispatched or sent through
another filter.
To see how to use filters read Zot-Dispatch: Filters.
The Document Root is the directory to which all filenames are assumed relative. It works much the same as with NCSA HTTPD Document Root, but is specified as:
DOC_ROOT Document Root
Where Document Root is the absolute path of the document root directory.
An example is:
DOC_ROOT /Web/doc
With the original version of Zot-Dispatch there was no Document Root, meaning
the document root was assumed to be /. If Document Root is set to anything
other than / there may be incompatibility problems for forms which used the
older version of Zot-Dispatch if they are switched to the newer.
Any files/directories listed in the Append Files section of the configuration file must be relative to the Document Root.
Files listed as the destination of an append or the source of a template can be specified either relative to the Document Root or as ~login. When referencing a file via the ~login mechanism the User Dir is the actual directory within login's home directory that is actually accessed. Much the same as with NCSA HTTPD's UserDir.
To specify the directory that is accessed within the user's home directory use:
USER_DIR Directory Name
Where Directory Name is the name of the directory to use. An example
is:
USER_DIR public_html
When using filters, Zot-Dispatch needs a place to temporarily store data. It will do so in a temp directory. To specify where your temp directory is use
TEMP_DIR temporary directory
where temporary directory is your temporary directory. An example is:
TEMP_DIR /tmp
Zot-Dispatch's log file is specified as:
LOGFILE filename
Where filename is the absolute location of the file to which Zot-Dispatch
will write its log information. An example is:
LOGFILE /Web/httpd/logs/zd.log
The log file must be created and the appropriate file permissions set before
running Zot-Dispatch. The permissions must be set such that the server can
write to the log file.
To set what the default subject line is for e-mail sent by Zot-Dispatch, use
DEFAULT_SUBJECT "Default Subject Line"
where Default Subject Line is the default subject line. An example is:
DEFAULT_SUBJECT "Results from Zot-Dispatch"
A macro block begins with the tag
<MACRO macro-name>,
where macro-name is the name you want associated with the macro. A macro
block is ended with the </MACRO> tag. Each entry in a
macro block represents one hidden variable in a form and is of the form
variable-name = "variable-value"
The double quotes mark the beginning and end of the variable-value,
so multi-line values may be used as long as you remember to use the double quote
at the end.
Double quotes can be embedded within the variable-value by preceding them with blackslashes as in: \"
Example of Macro:
<MACRO test-macro>
address = "lmegliol@uci.edu"
template = "body: Testing macro...
This is a multiline value"
ZD-Method = "ZD-Mail;$address#;$template#"
</MACRO>
This macro (called "test-macro") can be called by putting its name in the extra
path information when calling ZD. This particular macro will e-mail the
template to me.
Example of Macro use:
<A HREF=
"http://www.server/cgi-bin/zd-2.0.cgi/test-macro">Test Macro</A>
If you selected this link, Zot-Dispatch would be run using the variables listed
in the macro above (It would send mail to me).
We have made available a sample configuration file with all of it's values set to the defaults so that you can use it to begin configuring Zot-Dispatch for yourself.
lmegliol@uci.edu)