Soupermail Manual
Soupermail - a generic CGI WWW form handler written in Perl
<form method="post" action="/cgi-bin/soupermail.pl">
Soupermail is a generic HTML form handling script designed to provide a
high degree of control over a form's behaviour and output. It provides the
following features:
Soupermail can be used to handle single standalone forms, or generate and
control complex multipart forms.
Soupermail assumes some form fields have special meanings. These field names
ARE CASE SENSITIVE. The following is a list of such fields:
- Email
-
Assumed to be the email address of the form's sender. Needed if the email is to
be copied to the sender, or you are using a sendertemplate. When Soupermail
sends and email back, it will use the value of this field as the email's From:
address.
- SoupermailConf
-
This is a path to the configuration file that controls soupermail. The path
can either be relative to the location of the form, or an absolute path
from the webserver's root. If you are using soupermail to generate multipart
forms, it is recommended that you use absolute paths.
Soupermail is controlled on a per form basis by using configuration files.
Each form handled by soupermail must have an associated configuration file.
The location of the file is passed to soupermail through the PATH_INFO CGI
variable, or by using 'SoupermailConf' as a form parameter.
The PATH_INFO is set by providing a path after the call to soupermail
in the <form> element of the HTML page.
- eg.
-
If a form has a configuration file in /forms/config.txt, the form
should call soupermail with
<form method="post" action="/cgi-bin/soupermail.pl/forms/config.txt">
or as a form variable with:
<input type="hidden" name="SoupermailConf" value="/forms/config.txt">
The second method of supplying the config file is recommended. People
running under a cgiwrapped environment will have problems with the first
method, and even worse, the IIS webserver defaults to not supporting
the PATH_INFO method.
The path to the configuration file must be relative to the web server's
root directory. Do not use URLs or absolute paths to the configuration file.
The format for a configuration file is a series of configuration
statements of the form:
name : value
or
if : condition then name : value
or
unless : condition then name : value
If a badly phrased or incorrect configuration file is passed to soupermail,
it will complain, so always check your soupermail configurations carefully.
Valid names for the configuration file are:
- 7bit
-
This can be set to yes or no. If its yes, then email is sent
out encoded as quoted printable characters (i.e. 7bit safe). By default though,
email is sent out as 8bit, and its assumed the mailservers in the
transmission route will handle the 8bit conversions. You should only
need to alter this if you are experiencing character corruption in your
emails.
- alphasort
-
Set to yes or no. When email is sent without a
mailtemplate,
the form fields are displayed in the email in alphabetical order.
Setting this value to no does not sort the fields, and returns them
in the same order that the browser sent them.
- attachmentX
-
Files can be attached to email sent with
sendertemplate and
htmlsendertemplate. X is a number identifying the attachment.
See also listattachmentX
- eg.
-
attachment1 : /forms/download/myfile.pdf
attachment3 : file2.doc
- attachmentXmime
-
Since Soupermail doesn't know about MIME types, you may want to set a
specific MIME type for an attachment so receiving mail clients know how
to deal with them. By default, Soupermail sends text attachments as
text/plain and binary attachments as application/octet-stream.
See also listattachmentXmime
- eg.
-
attachment2 : /wordfile.doc
attachment2mime : application/x-msword
attachment5 : /forms/download/myfile.pdf
attachment5mime : application/pdf
- bcc
-
This is a comma separated list of email addresses to blind carbon copy on
the email sent to the
mailto addresses. See also senderbcc.
- blank
-
A template file to return to the user if they submitted a blank form.
- eg.
-
blank : /forms/config/blank.tpl
- blankmime
-
The MIME type that's returned to the browser for the
blank template. Also
see successmime, expiresmime and failuremime.
- cgiwrappers
-
Set to yes or no.
If you are running Soupermail in a CGI wrappers type environment, where
Soupermail's running with its owner's permissions rather than the webserver's
permissions, setting cgiwrappers to yes will make the
filereadable config command actually work.
- cookie[123456789]domain
-
This specifies the domain name that the cookie will be sent to. By default,
no domain is specified for a cookie. See the section on COOKIES for
more information.
- eg.
-
cookie1domain : myhost.domainname.com
Will only send cookie1 to pages on the myhost.domainname.com webserver. See
the section on COOKIES for more information.
- cookie[123456789]expires
-
A date or time format indicating when one of the nine available cookies
expires. Allowable formats can be relative. eg. +1h means one hour from
now, -2d means 2 days ago. The time periods allowable are s = second,
m = minute, h = hour, d = day, M = month, y = year.
Absolute dates and times can also be specified.
See the section on COOKIES for more information.
- eg.
-
cookie1expires : 1-4-1999 12:00:00
will expire the first cookie at midday on 1 April 1999.
cookie2expires : +1M
will expire the second cookie one month from when the form was submitted
By default, cookies expire 24 hours from when they were set.
- cookie[123456789]name
-
This sets the name of one of the nine available cookies to a value. See the
section on COOKIES for more information.
- eg.
-
cookie1name: zippy
sets the first cookie's name to 'zippy'
- cookie[123456789]path
-
This specifies which pathnames a cookie will be sent to. By default, this
will be to the location where soupermail is stored. See the section on
COOKIES for more information.
- eg.
-
cookie3path : /products
Would only send cookie 3 to pages below the /products directory of a website.
- cookie[123456789]secure
-
This is a yes or no value that specifies whether a cookie will be sent over
all connections, or just secure SSL connections. See the section on
COOKIES for more information.
- cookie[123456789]value
-
This sets the value of one of the nine available cookies. See the section
on COOKIES for more information.
- cookieonblank
-
If set to yes, this will send cookies when a blank form is detected.
- cookieonexpires
-
When set to yes, this will send cookies when a submission past an
expires date is sent.
- cookieonfailure
-
When this is set to yes, cookies will be sent out even if the form
has been considered a failure.
- cookieonsuccess
-
When set to yes, cookies are sent out when the form is considered a
success. This is the default behaviour.
- counterXfile
-
Each counter is stored on the webserver in a single file. The file simply
contains a number and should be specified in a directory that's writable by
the webserver. When a counterfile line is read into the config file, the
counter's value is made available for later use in the config file. See
COUNTERS for more information.
- counterXonblank
-
If set to
yes, this specifies that counter X will be incremented
if a blank form is submitted.
- counterXonexpires
-
If set to
yes this specifies that counter X will be incremented
if the form is submitted after its expiry date.
- counterXonfailure
-
If set to
yes this specifies that counter X will be incremented
if the form is missing required fields.
- counterXonsuccess
-
If set to
yes this specifies that counter X will be incremented
if the form is submitted successfully. The default is to increase the counter
by is 1.
- counterXstep
-
This is a positive integer value that specifies how much counter X
should be increased by.
- encodesubjects
-
By default, the Subject line of emails is assumed to be 7bit ASCII. However,
if you are sending non-ASCII characters, and have set the
mailcharset
option, then Subject lines are encoded as described in RFC 2047.
- error
-
This is an error message that you can generate and that becomes available
to use in the config file and templates as
http_config_error. If an
error is set, SQL commands will not run, and Soupermail will run in a
failure mode.
- expires
-
A date of the format dd-mm-yyyy after which the form cannot be submitted
- eg.
-
expires : 24-12-1998
This means the form would not be submittable after the 24st of December 1998
- expiresmime
-
The MIME type to return to the browser when
expirestemplate is sent
out. See also successmime, blankmime and failuremime.
- expirestemplate
-
A template file to use if the form has been submitted after its expires
date. See the section on TEMPLATES for more information.
- failure
-
A template to return to the user if they have not completed all the required
fields of a form. See the section on TEMPLATES for more information.
- eg.
-
failure : /forms/config/bad.tpl
- failuremime
-
The MIME type to return to the browser when the
failure template is sent
out. See also successmime, blankmime and expiresmime.
- fileattop
-
When writing the contents of a form to a file, new data is usually placed
at the end of the file. By setting
fileattop, new data can be written
at the start of the file (although after any specified header).
- eg.
-
fileattop : yes
- filebackupformat
-
This specifies a filename for backup files to be written into if a soupermail
generated file will grow over a
filemaxbytes limit.
The value for this can include formatting codes as listed in the
FORMATS section of this document. This lets you generate a number of backups
with a very fine level of detail.
The value specified in filereadable will affect any backup files generated.
- eg.
-
filebackupformat: /files/backup.txt
would always backup the file to /files/backup.txt
filebackupformat: /files/%yyyy%%mmm%%dd%backup.txt
would backup to /files/19980801backup.txt on 1 August 1998.
- filemaxbytes
-
This specifies the maximum size a soupermail generated file can grow to in
bytes. If a new addition would cause the generated file to grow over
filemaxbytes, then the file will be cleared of all other entries.
If you would like to save backup copies of the file, rather than simply
deleting it, specify a filebackupformat as described above.
To force a deletion after each entry, set the filemaxbytes to 1. Note that
setting it to 0 (zero), effectively resets filemaxbytes, and so has no
effect.
- eg.
-
filemaxbytes: 10000
- filepgpuserid
-
If you want to store the data from a form encrypted, you can use
filepgpuserid to securely store data.
- eg.
-
filepgpuserid: vittal.aithal@bigfoot.com
Will store data encrypted for vittal.aithal@bigfoot.com
- filereadable
-
When writing form data to a file, the file is usually kept unreadable by the
webserver. By setting
filereadable, the file can be made readable by the
webserver.
Note that this only affects people reading the file from a web browser, it
does not secure the file from other types of access (eg. from FTP or through
the filesystem). So, don't go storing credit card numbers in a file unless
you're damn sure that your machine's secure.
- eg.
-
filereadable : yes
- filetemplate
-
A template file which determines how a set of form data should be written to
the file specified by
fileto. See the section on TEMPLATES for more
information.
- fileto
-
The filename that the contents of a form should be written to. The path is
either relative to the location of the configuration file or an absolute
path from the web server's root.
- eg.
-
fileto : output/out.txt
If no filetemplate is given, the output form a form is written as a series
of lines matching:
name = value[,value ...]
Where a form field has multiple values, these are listed separated by commas.
- footings
-
This is a plain text file that can be placed at the end of files specified by
fileto.
- gotoblank
-
A URL for a page to redirect the user to if their form entry was blank. Unlike
the
blank field, the file is not a template, and so should not contain
<output> elements. CGI variable replacement can be used in the value of gotoblank to achieve PIPELINING.
- eg.
-
gotoblank : http://myserver/errors/blank.htm
- gotoexpires
-
A URL for a page to redirect to if the form has past its
expires date.
CGI variable replacement can be used in the value of gotoexpires to achieve PIPELINING.
- gotofailure
-
A URL for a page to redirect the user to if their form entry did not contain
all the required fields. Unlike the
failure entry, this is not a template
and should not contain <output> elements. CGI variable replacement
can be used in the value of gotofailure to achieve PIPELINING.
- eg.
-
gotofailure : http://myserver/errors/failed.htm
- gotosuccess
-
A URL for a page to redirect the user to if their form entry was successfully
completed. Unlike the
success field, this is not a template and should
not contain <output> elements. CGI variable replacement can be
used in the value of gotosuccess to achieve PIPELINING.
- eg.
-
gotosuccess : http://myserver/forms/success.htm
- gnupg
-
It is possible to use the GNU Privacy Guard program rather than PGP. If you
do use it, then set
gnupg to yes in your configuration. If you do not,
then Soupermail will assume encryption is using PGP. This command is now
deprecated in favour of pgpversion.
- headings
-
This is a plain text file that can be placed at the start of files specified
by
fileto.
- htmllisttemplate
-
The HTML email template to use for the MAILING LISTS function. This
and/or a
listtemplate must be used for mailing lists to work.
- htmlmailtemplate
-
This option allows you to send mail formatted in HTML. Only the HTML
is sent, images are not encoded or sent. All relative links from the HTML
will be from the location of the config file on the server.
Probably the best thing to do with HTML templates is use absolute URLs
for images and suchlike.
If you specify both htmlmailtemplate and mailtemplate a mixed
text and HTML message is generated. This will allow people who don't have
HTML capable mail clients to read your mail.
- htmlsendertemplate
-
In the same way as
htmlmailtemplate is sent to the mailto address, this
template is used when sending mail to the submitter of the form. It behaves
in the same way as htmlmailtemplate when it comes to link handling.
- ignore
-
If your HTML forms contain hidden fields, you can
ignore them so that
you can check for situations where the user doesn't complete any fields. Only
one form field can be specified on an ignore line. Use multiple ignore lines
if you wish to ignore more than one field. The soupermail special form
variable SoupermailConf is ignored automatically.
- eg.
-
ignore : hidden1
ignore : hidden2 This would ignore the values of fields 'hidden1' and 'hidden2'
when determining if a form was left blank.
- if
-
A conditional statement used to set configuration values based on the user's
form input. See the section on CONDITIONAL STATEMENTS for more information.
- eg.
-
if : (division eq 'Accounts') then mailto : accounts@mycompany.com
This would set mailto to accounts@mycompany.com if the form contained
a field called 'division' and its value was 'Accounts'.
- iscreditcard
-
This is used to validate a form field to see if its a credit card number.
The check performed is a basic Luhn checksum, and doesn't check card
ranges.
- eg.
-
If you have a field called 'creditc' in your form, and want to validate it,
use:
iscreditcard: creditc
If the validation fails, the failure template is activated. Validation will
not fail if the field is left blank.
- isemail
-
This is used to validate a form field is an email address. If the validation
fails, the failure template is activated.
- isinteger
-
This is used to validate a form field is an integer. If the validation fails,
the failure template is activated.
- isnumber
-
Behaves in the same way as the isinteger option, and validates a form field
as a number.
- isnotcreditcard
-
Used to check is a form field is NOT a credit card number.
- isnotemail
-
Used to check is a form field is NOT an email address.
- isnotinteger
-
Used to check is a form field is NOT an integer.
- isnotnumber
-
Used to check is a form field is NOT a number.
- listattachmentX
-
This defines an attachment that is sent from the server to each mail
sent to the mailing list. Its syntax is the same as that of
attachmentX.
- listattachmentXmime
-
This is the MIME type for an attachment sent to the mailing list.
See
attachmentXmime for the syntax.
- listbase
-
When HTML email is sent to a mailing list, Soupermail inserts a
Content-Location email header based on the submitting form's URL. Use this
option to modify it for your own needs. Similar to
senderbase and
mailbase.
- listfrom
-
The email address to use in the From: field for emails sent out using
Soupermail's MAILING LISTS function.
- listformfield
-
Sometimes, you may want to send emails to a mailing list
sent to the form through a form field. This config command says
which form field contains this data.
- listprecedence
-
When email is sent out with Soupermail's MAILING LISTS function, the
Precedence mail header is set to prevent mail loops. It can take one
of three possible values; list, junk and bulk. By default, the
Precedence value is list.
- listreplyto
-
The email address to use in the Reply-To: field for emails sent out using
Soupermail's MAILING LISTS function.
- listsql
-
The data for a mailing list can be pulled from a SQL database as long as
the
sqlname, sqluser, sqlpassword and appropriate sqlbind
values have been set. listsql is an SQL command in the
same format
as sqlrunX commands.
The data returned from the SQL statement must have the user's email
address as the first column.
- listsubject
-
The Subject: line to be used for emails sent out using the
MAILING LISTS function.
- listtemplate
-
The plain text message template to use for the MAILING LISTS
function. This and/or a
htmllisttemplate must be specified for a
mailing list to work.
- mailbase
-
When HTML email is sent to the
mailto address, Soupermail inserts a
Content-Location email header based on the submitting form's URL. Use this
option to modify it for your own needs. Similar to senderbase and
listbase.
- eg.
-
mailbase : http://www.example.com/graphics/
- mailcharset
-
This defines the character set to send email as. It defaults to iso-8859-1.
- maillist
-
This option is the location for a MAILING LISTS file.
- eg.
-
maillist : /forms/config/mynames.csv
- mailtemplate
-
A template file to use when formatting the outgoing email. See the section
on TEMPLATES for more information.
- eg.
-
mailtemplate : /forms/config/mail.tpl
- mailto
-
A comma separated list of email addresses to send the results of the email to.
- eg.
-
mailto : rod@mycompany.com, jane@othercompany.com, freddy@mycompany.com
- mimeon
-
When set, Soupermail will allow file uploads from web browsers using RFC1867
and will attach the uploaded files as MIME attachments on resulting emails.
- eg.
-
mimeon : yes
This would allow MIME attachments to be sent.
- nofilecr
-
When saving results to a file, it is sometimes useful to remove newline
characters from the results. Setting
nofilecr will do this.
- eg.
-
nofilecr : yes
This would remove newline characters from fields written to a file.
- nomailfooter
-
Do not display the hostname and IP address details at the foot of each
outgoing email.
- eg.
-
nomailfooter : yes
- pdftemplate
-
This is a lout template file that will be processed into a PDF and returned
to the browser. If you want to use this option, don't specify a
success
template in your config file. See the MAKING PDFs section for more
details.
- pdfmailtemplate
-
This is a lout template file that will be processed into a PDF and returned
to the
mailto email recipient as an email attachment. It can be used
in conjunction with mailtemplate and htmlmailtemplate.
- pdfsendertemplate
-
This is a lout template file that will be processed into a PDF and returned
to the email address given in the Email form field. It can be used
in conjunction with
sendertemplate and htmlsendertemplate.
- pgpmime
-
By default, Soupermail will send PGP messages as a multipart/encrypted MIME
message (as per RFC 2015). However, not all PGP mail plugins recognise
this format (eg, the Pegasus mail PGP plugin). Setting pgpmime to no
will not encapsulate the PGP message in MIME headers.
- pgppdfs
-
If set to 'no', then PDF's generated with Soupermail are NOT encrypted when
sent. Instead, they are attached to the encrypted content of the email.
The default behaviour is to encrypt PDFs.
- pgpport
-
This is the port number of a HTTP PGP 5 keyserver. The default port is
11371. The hostname for the server is specified with pgpserver below.
See the section on USING PGP for more information.
- pgpserver
-
This is the hostname of a HTTP PGP 5 keyserver to get PGP keys from.
See the section on USING PGP for more information.
- eg.
-
pgpserver : pgpkeys.mit.edu
- pgpuploads
-
If set to 'no', then uploaded files are NOT encrypted when
sent. Instead, they are attached to the encrypted content of the email.
The default behaviour is to encrypt uploaded files.
- pgpuserid
-
A user in the public keyring which outgoing email should be encrypted for.
See the section on USING PGP for more information.
- eg.
-
pgpuserid : bungle@mycompany.com
- pgpversion
-
From version 1.0.8, this is the prefered mechanism for selecting the
type of encryption to use. Values for this can currently be
'gpg', 'pgp2' and 'pgp5'. By using this field, future versions of PGP and
GNUPG can be supported.
- ref
-
A format for a reference number to be generated and used as the
http_ref CGI variable. See the sections on CGI VARIABLES and
FORMATS for more information.
- eg.
-
ref : REF%yy%%mmm%%dd%%rrrr%
This may generate a reference like: REF9704016364 on April 1 1997
- replyto
-
An email address that will be used in the Reply-To: mail header.
- eg.
-
replyto : zippy@mycompany.com
- required
-
A boolean expression which determines which form fields must be completed.
The entry is composed of field names separated by && (AND) and || (OR)
operators. See the section on Boolean Expressions for more details.
- eg.
-
required : ((name && address) || telephone)
The above expression requires either the fields name and address to be
completed, or the field telephone to be completed.
- returntosender
-
This will CC the sender of the form a copy of the email message sent as a
result of the form. This requires the form to have a field called Email (case
sensitive), which is assumed to be the sender's email address.
- eg.
-
returntosender : yes
- senderbase
-
When HTML email is sent to the submitter of a form, Soupermail inserts a
Content-Location email header based on the submitting form's URL. Use this
option to modify it for your own needs. Similar to
listbase and
mailbase.
- senderbcc
-
This is a comma separated list of email addresses to blind carbon copy on
the email sent to the form's sender when a
sendertemplate is specified.
See also bcc.
- senderfrom
-
When using a
sendertemplate, the email address used in the email back to
the form's sender is set to this. The preferred order email addresses are
chosen for the sender's From field is:
This field is useful if you need an auto-reply function from your form, but
don't want to obviously expose the mailto address directly to the sender of
a form.
- senderreplyto
-
An email address that will be used in the Reply-To: mail header for mails
sent with the
sendertemplate config option.
- sendersubject
-
Used in conjunction with
sendertemplate, this is a subject line only to
be used in email messages send directly back to the form's submitter. If its
not set, the subject line set with the subject config line is used.
- sendertemplate
-
This is a template file for an email to be sent back to whoever submitted
the form. It takes the email address to send this to from the Email
form variable. The From field of the email is set to either the
mailto
or replyto configuration values. See the section on TEMPLATES for
more information.
- setcounterX
-
This sets the value of a counter prior to any templates being filled based
on the counter's onsuccess, onfailure, onblank and onexpires config
values.
- sqlbindX
-
Using the
sqlbind command allows you to specify a variable that will
be used in the next SQL statement specified by a sqlrunX command.
- eg.
-
sqlbind2: "$form_second_field"
sqlrun1: SELECT * FROM TABLE WHERE field1 = ? AND field2 = ?
In this example, the value of the form field "second_field" is
used to replace the second question-mark value in the SQL statement.
Binding does all the character escaping needed by the SQL, so there
is no need to enclose strings in single quotes.
- sqlname
-
This is the DBI name for the next database connection you will use.
You can use multiple connections during the course of a config file.
The format for the name is the normal DBI format.
- eg.
-
sqlname: dbi:mysql:database=test;host=mysql.example.net
- sqlpassword
-
This is the connection password that will be used for the next SQL
command run in the config file. Usually used with
sqluser.
- eg.
-
sqlpassword: my_random_password
- sqlrunX
-
Multiple SQL statements can be executed in a config file, and
each statement is defined by a
sqlrunX command. Statements are
executed in the order they are seen in the config file, working from
top to bottom.
The number at the end of the sqlrunX name is used to
identify the results of the command for later use in the config
file and in templates.
Variables that you want to use in your SQL command that come from
form, cookie or counter data must be passed in by binding the
values. Binding involves using a question-mark character to represent
a variable, and setting a sqlbind command to indicate something to
use.
- eg.
-
sqlbind1: "$form_name"
sqlrun1: SELECT id FROM users WHERE name LIKE ?
The bind command attaches the value of the form field to the first
question-mark in the next SQL statement. In this case, if the
value of the form field 'name' was 'fred', then the SQL command
would become:
SELECT id FROM users WHERE name LIKE 'fred'
For security reasons SQL commands will not run if there are
required, or invalid field types.
- sqluser
-
This is the username to use when connecting for the next SQL statement.
Usually used with
sqlpassword.
- eg.
-
sqluser: root
- subject
-
A subject line to use on resulting emails.
- eg.
-
subject : This is a feedback email
- success
-
A template file to return through the web browser if the form was correctly
submitted. See the section on TEMPLATES for more information.
- eg.
-
success : /forms/config/success.tpl
- successmime
-
This allows you to specify a specific MIME type for the data returned
back to the browser by the
success template. Values given here should
be of the form word/word. Its related to the failuremime,
blankmime and expiresmime config commands.
- eg.
-
successmime : text/xml; charset=utf8
- unless
-
This has an identical format to the
if command, but performs the opposite
of what the if tests do. Using this, you can check for when values are not
set. See the section on CONDITIONAL STATEMENTS for more information.
- wrap
-
The number of characters to wrap the soupermail emails to.
- eg.
-
wrap : 60
Sometimes it is useful to concatenate some of the configuration values, for
instance where you need to specify more that one mailto recipient based
on the user's input. In order to do this, you can use the following variables
in you configuration files:
- $mailto
-
This is the current value of
mailto in the configuration. This will be
expanded to the value when the configuration is parsed.
- eg.
-
mailto : rod@mycompany.com
mailto : "$mailto, jane@mycompany.com" This example initially sets mailto to rod@mycompany.com. Then it sets
mailto to rod@mycompany.com, jane@mycompany.com. Notice that the expansion
occurs only if the value is enclosed in double quotes (").
- $subject
-
This is used to get the current value of
subject
- eg.
-
subject : Feedback of type -
if (feedtype eq 'comment') then subject : "$subject Comment"
if (feedtype eq 'problem') then subject : "$subject Problem" This example changes the subject based on a field in the original form
called 'feedtype'.
- $replyto
-
This is used to get the current value of the
replyto field.
- eg.
-
replyto : management@mycompany.com
if : (interested has 'rod') then replyto : "$replyto, rod@mycompany.com"
if : (interested has 'jane') then replyto : "$replyto, jane@mycompany.com"
if : (interested has 'freddy') then replyto : "$replyto, freddy@mycompany.com"
If the form contained a set of checkboxes all called 'interested' with the
values of 'rod', 'jane' and 'freddy', this configuration will add the email
addresses of rod, jane and freddy depending upon which checkboxes were set
by the user.
- CGI variables
-
It is possible to use all of the CGI VARIABLES listed below
by placing a '$' character before their name.
- eg.
-
$http_user_agent
will return the web browser name.
- Form Variables
-
It is possible to use any value from a form by placing '$form_' before the
form variable's name.
- eg.
-
If a form has a field called 'TheirName', then the following could be used in
the configuration file:
Subject: "Form response from $form_TheirName"
- Cookie Variables
-
In the same way as its possible to use form variables, cookie variables can
be inserted by putting '$cookie_' before the cookie's name.
See the section on COOKIES for more information.
- eg.
-
Subject: "The cookie named Bungle has value $cookie_Bungle"
Replacements can only be used when setting the subject, mailto, replyto,
reference number and cookie value fields.
Replacement value will only be used when they are enclosed in double-quotes.
So, the following will NOT work:
- eg.
-
Subject: This is a non-working mail to $mailto
However, this will work:
- eg.
-
Subject: "This is a working mail to $mailto"
Conditional statements in configuration files allow you to control the
configuration of a form based on the user's form input, values from a
users cookies or any of the http_ variables. A conditional
statement is made up of a boolean expression followed by a configuration
statement.
- ie.
-
if : boolean_expression then configuration_statement
or
unless : boolean_expression then configuration_statement
The only configuration statement disallowed in a conditional statement is
another if or unless.
Conditional statements are executed in the same order that they appear in
the configuration file.
A boolean expression is something that can either be true or false. If it's
true, then the configuration statement is set, otherwise it isn't.
The simplest boolean expression is just the name of a form field. If the form
field was completed by the user, then the boolean is true.
- eg.
-
If you have a form that contains and input field called 'name' and you want to
set the
subject line based on this name being set, you could use the
following configuration statements:
subject : They haven't set their name
if : name then subject : They have set their name! Initially, subject is set to 'They haven't set their name'. However, if the
'name' field is completed on the form, the conditional statement is
activated and the subject is reset to 'They have set their name!'.
If you want to check on cookies, prefix the cookie's name with $cookie_. So,
if you wanted to test if the user had sent a cookie called "MyName", use
a condition like this:
- eg.
-
if: $cookie_MyName then Subject: "Cookie MyName was set to $cookie_MyName"
Boolean expressions in soupermail use three basic operators, AND (&&),
OR (||) and NOT (!). An expression with an AND in will be true if
BOTH of the things around the AND are true. An expression with an OR
in will be true if one or more of the things around the OR is true.
An expression preceded by a NOT will be true if the thing following
it is false.
- eg.
-
x && y will be true if x is true and y is true
x || y will be true if x is true or y is true
x && y || z will be true if x and y are both true, or
x is true.
!x will be true if x is false.
Boolean expressions can contain any number of smaller boolean expressions.
To make life easy, you can group these with brackets "(" and ")".
- eg.
-
You have a form containing the fields 'name', 'address', 'telephone', 'fax' and
'Email'. You want to know that name has been filled in and that they have
supplied an address or telephone or email. The following boolean expression
could be used:
name && (address || telephone || Email)
Notice the use of brackets, to enclose the ORs. If the brackets were missed
out, the expression would have meant the user must complete their
name and address, or their telephone, or their email; or as a boolean
expression:
(name && address) || telephone || Email
This is because AND is considered to be more important than OR.
If you have form fields that contain spaces, you can still use them in boolean
expressions, but you must enclose them in double quotes (").
- eg.
-
You have a form containing:
<input type="text" name="First Name">
Any boolean expression using this field name must use it quoted:
"First Name"
Other operators available in boolean expressions are:
- ==
-
Numerical equality
- eg.
-
if : age == 45 then subject : You are 45
- !=
-
Numerical inequality
- eg.
-
if : age != 50 then subject : You are NOT 50
- <=
-
Numerically less than or equal to
- eg.
-
if : age <= 50 then subject : You are younger than 51
- >=
-
Numerically greater than or equal to
- eg.
-
if : age >= 50 then subject : You are older than 49
- <
-
Numerically less than
- eg.
-
if : age < 50 then subject : You are younger than 50
- >
-
Numerically greater than
- eg.
-
if : age > 50 then subject : You are older than 50
- eq
-
String equality
- eg.
-
if : name eq 'Humphry' then subject : You are called Humphry
- ne
-
String inequality
- eg.
-
if : name ne 'Humphry' then subject : You are NOT called Humphry
- le
-
String less than or equal to
- ge
-
String greater than or equal to
- lt
-
String less than
- gt
-
String greater than
- has
-
A string value is equal to something in a multivalue field
- hasnt
-
A string value is not equal to something in a multivalue field
- contains
-
A string value exists inside, or is equal to another value. It is
case-insensitive.
- eg.
-
if : name contains 'on' then subject: Your name contains the letters on
The above example would match names such as "Ron" or "Donna".
- longerthan
-
Returns true if the value to the left is made of more characters
than the value to the right.
- eg.
-
if : name longerthan 5 then subject: Your name has more than 5 characters
- shorterthan
-
Returns true if the value to the left is made of less characters
than the value to the right.
- eg.
-
if : name shorterthan 5 then subject: Your name has less than 5 characters
Soupermail uses a series of templates specified by the configuration file to
control the output, either to the screen, a file or to email. All the
template locations should be specified relative to the location of the
configuration file, as absolute paths (things starting with a '/' character)
from the web server's root, or as private paths (things starting with
a '~' character). The basis for a template are the
HTML-like elements called <output>, <only> and
<loop>.
Templates can be used for emails, files and pages returned to the browser.
Templates returned to the browser can be given different MIME types, meaning
you can return things like WML for WAP sites.
When sending HTML email templates, you can set the base for images embedded in
the email with the listbase, mailbase and senderbase commands.
The <only> element defines a block in a template to use if its
if attribute is matched. The if attribute should contain a boolean
expression. See Boolean Expressions for more information about
what the if attribute can contain.
- eg.
-
<only if="month == 12">
Its December, so here's December's calendar:
<!--#include virtual="dec.txt"-->
</only>
<only> elements cannot be nested, but they can contain any number of
<output> elements and includes.
<loop> elements allow one part of a template to be repeated multiple
times. Using loops, you can repeat a section of template a fixed number of
times, or loop through the values of form field.
Loops can take five attributes:
- start
-
If you need to control when a loop starts, the start attribute sets
the initial value of the loop. This can be any number.
- end
-
This is the final value of the loop. It can be any number. If the value of
end is greater than the value of start, the loop counts forward in steps
of one. If the value of end is less than the value of start, the loop counts
backward in steps of minus one.
- name
-
Each time Soupermail goes through a loop, you can take the current value
of the loop, and use it in the template. To get the value, you need to
refer to it by the loop's name.
To get the value out, surround the loop's name by @ characters inside
the loop block.
- eg.
-
<loop name="loopvalue" start="1" end="5">
@loopvalue@
</loop> This loop will return '1 2 3 4 5'.
- step
-
The default step in loops between the start and end values is one.
With the step attribute, you can change this value. Step can take
any number as a value.
- eg.
-
<loop name="loopvalue" start="1" end="5" step="2">
@loopvalue@
</loop> This loop will return '1 3 5'.
- field
-
When you need to use a loop to run through the multiple values
of a form field the field attribute is used to specify which
field to loop with.
- eg.
-
If you have a SELECT element in your form like this:
<select multiple="multiple" name="multiselect">
<option>value one
<option>another value
<option>yet another value
</select> you can use the following loop to get the values:
<loop name="selectfield" field="multiselect">
One of the values is @selectfield@
</loop>
The <output> element can be considered as analogous to the HTML
<input> element.
Where an <output> element appears in a template, Soupermail
replaces it with some appropriate text. The value of the replacement
text depends upon the attributes specified in the <output> element.
The following is a list of attributes that can be placed in template
<output> elements.
- alt
-
This field is alternative text to replace the <output> element
with, if the field name wasn't filled in on the original form.
- altvar
-
Usually, the value of the
name attribute is replaced in the
<output> element. However, using altvar, another variable
can be used if name hasn't a value.
- eg.
-
Supposing you have a field called 'month' that you want to default to the
current month if it's not filled in in the form. The following could be
used:
<output name="month" altvar="http_date" format="%mmm%">
- case
-
This can take the values of upper or lower and will upcase or
downcase the thing returned by the output element.
- charmap
-
Sometimes, you need to change one character in a string to another; for
instance, escaping quote marks when saving a CSV file. The
charmap
attribute allows a character to be changed to a string (or removed). The
format for the charmap attribute should be the character to change,
followed by a comma, followed by the string to change it to.
- eg.
-
To double up quote marks for a CSV file, use something like:
<output name="fieldname" charmap='",""'>
To remove all occurrences of the letter 'a':
<output name="fieldname" charmap="a,">
To turn underscores into hyphens:
<output name="fieldname" charmap="_,-">
- data
-
This is used to check the type of data in the form field. The
data attribute
can have the following values: number, notnumber, integer,
notinteger, email, notemail, creditcard, notcreditcard
If the check fails, then the output element will return its alt value.
- eg.
-
Here are some examples for a form field, 'foo', with a value of 6.5:
<output name="foo" data="number" alt="fail" sub="pass"> = pass
<output name="foo" data="integer" alt="fail" sub="pass"> = fail
<output name="foo" data="notnumber" alt="fail" sub="pass"> = fail
<output name="foo" data="notinteger" alt="fail" sub="pass"> = pass
<output name="foo" data="email" alt="fail" sub="pass"> = fail
The credit card check is a simple LUHN checksum that makes sure the number
given looks like a credit card number. It does not mean the number is a real
card number, or that there's any money in the account.
- delim
-
A text string to display between items in a text
list.
- format
-
A format to specify how certain variables are formatted when displayed. Only
applies to http_time, http_date and http_ref.
- indent
-
This is a string to indent the substituted text with. Its mainly useful
for email templates, where you may want to indent the contents of an HTML
textarea element.
- list
-
When an <output> element is replaced by a multivalued form field,
Soupermail's default behavior is to output a HTML <ul> list, or
text list. By setting the
list attribute to ul|ol|menu|dir|text, a
specific type of HTML list can be achieved. The text value will return a
non-HTML text list. The format of this text list can be controlled by the
delim attribute.
- math
-
You can use simple maths expressions using this attribute. You can use
form, cookie and http values in the
math expression, and they will be
replaced before the expression is evaluated. Values that are undefined or
non-numeric are replaced by zero. If the name attribute is multi-valued,
the math expression is evalued for each value.
The following are the maths operators available:
- +
-
addition
- -
-
subtraction
*
-
multiplication
- /
-
division
sum()
-
summation of a multiple valued field
count()
-
count of a multiple valued field
To add two fields together:
<output name="field1" math="field1 + field2">
To calculate an average of a number of fields:
<output name="field1" math="(field1 + field2 + field3) / 3">
- name
- This should correspond to a field name from the HTML form, a CGI
Variable available from Soupermail a cookie name, a counter value,
a mailing list value or a SQL value.
CGI variables start with 'http_', counter values
start wit 'counter_', cookie values start
with 'cookie_', mailing list values start with 'mailist_' and SQL values
start 'sql_'. This field is case-sensitive.
- newline
-
This allows newlines to be represented as either HTML or removed from the
value. If
newline has the value html, then newline characters
are converted to <br> tags. If it has the value of none, then
newline characters are replaced by spaces. If it has a value of
unchanged then newlines are left as is. The value of paragraphs
replaces breaks of more than 2 newlines with only 2 newlines - useful
for formatting plain text entries.
- post
-
This is text to be post-pended to the value of the field name if the
field was set in the original form. It isn't used with the
alt or sub
attributes. For multivalue entries, the post section is placed after each
list item.
- pre
-
This is text to be pre-pended to the value of the field name if the field
name was set in the original form. It isn't used with the
alt or
sub attributes. For multivalue entries, the pre section is placed
before each list item.
- precision
-
Used in conjunction with the
math attribute, this value is the number of
decimal places to display numbers to.
- sub
-
This is text to replace the output field with if the field is set in the
original form.
- subvar
-
This is similar to the
altvar attribute, but comes into play when the
variable set be the name attribute has a value.
- timeoffset
-
This is used for providing a time offset when outputting
http_time and http_date values. Values should be of the form:
[+|-]num[smhdMy]
Where, the initial plus and minus indicate the direction of the offset,
num represents how much to offset by, and s indicates an offset in
seconds, m an offset in minutes, h an offset in hours, d an
offset in days, M an offset in months and y an offset in years.
- type
-
If type is set, it can be one of escaped, unescaped, html or
unescapedhtml. Escaping output tags is useful if you want to pass
form values between forms in hidden form fields. Escaped output tags
are URL encoded, so characters such as < and " don't appear.
When you want to get the user's original values, use the unescaped
or unescapedhtml types in an output tag. The html type is useful
for displaying values in HTML templates where a user may have typed in
HTML characters such as < or >.
- eg.
-
If you have a field like this:
<input type="text" name="val">
and this in a template:
<input type=hidden name=val value="<output name="val">">
and the user's typed something like this into the field:
The "sum" is > than the "parts"
If you don't escape the output tag, you get broken HTML like this:
<input type=hidden name=val value="The "sum" is > than the "parts"">
However, if you used <output name="val" type="html">, you'd get:
<input type=hidden name=val value="The &#34;sum&#34; is > than the &#34;parts&#34;">
which is HTML safe.
- value
-
Usually, if the thing set by
name has a value, it is returned by the
<output> element. However, if value is set, it is only returned
if its value equals that of value. The alt attribute will become active
if the values do not match and the sub attribute will become active if
they do match. This may sound pretty daft, but its
useful for regenerating drop down lists in multipart forms. See the
Multipart form example that comes with Soupermail.
- valuevar
-
Similar to the
value attribute, but affects the use of altvar and
subvar replacement.
- wrap
-
An integer specifying how many characters to wrap the output value to.
Wrapping occurs after any maths, charmap or HTML conversions have
been applied to the value, but before the PRE and POST attributes take
effect. This attribute is useful for formatting HTML textarea elements.
Server Side Includes (SSI) are a means of dropping one file into another
before sending a page onto the user's browser. Soupermail can provide a basic
inclusion mechanism using the same syntax as normal SSI directives. Soupermail
will only handle <!--#include virtual="..."--> type includes, #exec
is too much of a processing burden. The path can either be an absolute path
from the server's root, or a path relative to the location of the config
file.
If you are putting the include into a HTML page, and don't want characters
like < to be specially treated by the browser, then you should put the
type="html" attribute in the include call:
<!--#include virtual="..." type="html"-->. ALWAYS do this if
you do not trust the source of the include.
CGI variables are set by the web server, and in some specific cases, Soupermail.
These names should not be used as field names in your HTML forms.
- counter_X
-
The value of the counter named X
- http_time
-
The time at the web server.
- http_date
-
The date at the web server.
- http_referer
-
The URL of the calling form.
- http_remote_host
-
The hostname of the person sending the form.
- http_remote_addr
-
The IP address of the person sending the form.
- http_server_name
-
The name of the webserver.
- http_server_port
-
The port number the webserver is listening on.
- http_user_agent
-
The type of browser used to send the form.
- http_ref
-
A soupermail generated reference number.
- http_remote_user
-
The username if the form was password protected.
- http_remote_ident
-
Not sure, but some browsers set it.
- http_host
-
The server name the browser thinks its at.
- http_from
-
A browser specific variable
- http_config_error
-
The last error message set in the config file with the
error config command.
- http_config_path
-
The path from the web server's root to the configuration file
that was used to generate the page. This can be very useful
when generating multipart forms, where you want to keep your
directory structure portable by using relative links.
- maillist_X
-
This is a value from the current
mailist line of data. X is the
column number of the data to use. Columns start at one (the email
address). See MAILING LISTS for more information.
Formats allow the http_time, http_date and http_ref variables to be controlled.
A format is a one line string containing the following substrings. When the
<output> element is expanded, the substrings are expanded into the
following:
- %yyyy%
-
A 4 digit year (eg. 1997)
- %yy%
-
A two digit year (eg. 97)
- %mmmm%
-
A three letter month code (eg. Jan)
- %mmm%
-
A two digit month code
- %ddd%
-
A three letter day code (eg. Mon)
- %dd%
-
A two digit day code (eg. 28)
- %hhhh%
-
A 2 digit 24 hour (eg. 13)
- %hh%
-
A 2 digit hour (eg. 03)
- %mm%
-
A 2 digit minute (eg. 23)
- %ss%
-
A 2 digit second (eg. 06)
- %ampm%
-
Either 'am' or 'pm' depending on what the time is.
- %epoch%
-
Return the epoch time for your system. On UNIX, this is the number of seconds
since 00:00:00, 01/01/1970.
- %r...%
-
A random number. The length of the random number is determined by the
number of r's in the format. The maximum number of r's is 12. eg. %rrr% returns
a value between 0 and 999.
- %c...%
-
This is a formatting command used to break a number into a series of
space delimited blocks. The number of c characters given determines
how many characters to use before a space.
- eg., to format a credit card number
-
use
format="%cccc%" which would give you something like:
1234 5678 9876 5432
format="%ccc%" would give you:
123 456 789 876 543 2
Non-numeric characters are removed from the value.
- %counter_X%
-
This is the value of a config file specified counter. The value used is
calculated after any increments or sets are performed on the counter, so
it will be the same value that appears in templates. The value of X is
the counter number needed. eg. %counter_3%
Counters are a way of storing and reading the number of times Soupermail has
done something. They are specified in the configuration file, and you can have
any number of them in use. In their simplest guise, you can use them to count
how many people have submitted a form. More complex uses include setting
the maximum number of times a form's submitted, online voting systems
and renaming the filenames form information is saved to.
The behaviour of counters can be slightly odd for the unwary. Firstly, they
are always defined in the config file, but simply declaring a counter file
does not mean it gets updated, its value just becomes available for the config
file and for templates. To update a counter, an onsuccess, onfailure, onblank
or onexpires setting for the counter must be set.
Secondly, the value returned by a counter in the config file is the value
stored in the counter file BEFORE any increments have been performed on the
counter, however, the value returned in templates and the http_ref value
are set AFTER increments have been applied to the counter.
- eg.
-
mailto: cookiemonster@example.org
counter1file: counters/count1.txt
counter1onsuccess: yes
if : ("$counter_1" == 10) then setcounter1 : 1
if : ("$counter_1" == 10) then mailto : thecount@example.net
The above example would result in counter1 being set to 1 and the mailto
address set to thecount@example.net whenever the counter reached 10.
Note that even though the
setcounter1 is set in the config file, it does not have an immediate
effect, and does not prevent the second if statement being used.
Cookies were introduced in Netscape Navigator 2.0. They are a means of
storing information on the user's browser even after they've turned off their
computer. Soupermail allows up to nine cookies to be set, each cookie holding
at most 516 characters worth of data, and with a cookie name less than 50
characters long. The restriction on the cookie size and number of cookies
is mainly out of politeness, because its not considered nice to flood users
with cookies.
More information on cookies can be found at
http://home.netscape.com/eng/mozilla/3.0/handbook/javascript/index.html
PGP is a means of encrypting text through a public key and decrypting through
a private key. Using PGP, Soupermail can send secure encrypted email over
an insecure Internet.
To use PGP, you will need to place a public keyring (pubring.pkr for
PGP 5, pubring.pgp for PGP 2.6.3 or pubring.gpg for GPG) in the
directory where your form's configuration file is located. In your
configuration file, set pgpuserid to be a user in the pubring keyring.
When soupermail generates an email, it will encrypt the message using the
public key of the given user. By default, this version of Soupermail
assumes that GPG is being used.
As of Soupermail 1.0.3, GNU Privacy Guard (GPG) is supported as an alternative
to using PGP. Using GPG rather than PGP differs only in that the public
keyring file is called pubring.gpg. The pgpversion config option must be set
to choose between the different encryption methods. See the GPG documentation
for more information.
If you have problems using PGP or GPG, make sure your webserver has the ability
to run the scripts - some server installations may not give the nobody user
rights for this. Generating a debug file is the best diagnostic option.
Versions of Soupermail greater than 1.0.8 have support for PGP 5.0i and 2.6.3i
(I've only tested the international versions so people using US versions may
have different results).
You can also specify a PGP keyserver in the configuration file. If specified,
the PGP encryption will look on the key server for encryption keys.
THE PGP KEYSERVER CODE IS EXPERIMENTAL AND HASN'T BEEN TESTED! USE AT YOUR
OWN RISK!
For more information on PGP, please look at http://www.pgpi.org/
For more information on GPG, please look at http://www.gnupg.org/
From version 1.0.7, Soupermail can generate Adobe PDF files by hooking up to
lout and ghostscript.
Lout is a nifty document formatting language, which is used to generate
postscript files. Ghostscript is a postscript processor which can generate
PDF files (amongst other things).
To use this feature, you're going to have to look into how lout templates work.
Its a powerful language, so spend some time delving though the documentation
that comes with lout. Basically, Soupermail hooks into lout by allowing
you to use <output> elements in lout templates. Soupermail reads
the lout templates you specify with the pdftemplate config options, fills
in the <output> elements, then passes this on to lout and
ghostscript to handle. The results can be emailed out, or returned to
the browser depending on the config options you have used.
One of the nice things about using lout and ghostscript together is
the ability to include EPS images in your generated PDFs. To do this,
place your EPS files in the same directory as your lout templates and
use lout's include image command in your templates. Soupermail assumes that
EPS files end in a .eps file extension.
The Soupermail example files contain an example of using Soupermail's
PDF commands.
To use the PDF commands, you'll need to install GhostScript from
http://www.cs.wisc.edu/~ghost/index.html and Lout from
ftp://ftp.cs.usyd.edu.au/jeff/lout/.
Version 1.0.7 of Soupermail brings along mailing lists, which are ways of
sending Soupermail generated email to a set of people defined in a
file. To do this, you should specify a maillist file in your form's
configuration. The maillist file should be a set of lines, each one
starting with and email address, and with other optional columns following,
separated by commas.
- eg.
-
foo.bar@example.net,Mr Foo,nothing special
fred.bloggs@example.com,"Bloggs, Fred",geezer
xyz@example.com,XYZ Man,unable to think of a better name,other stuff
As you should see from the example, there can be any number of extra
columns of data in the file. When Soupermail is given a mailing list file,
it generates an email for each address in the file based on the
listtemplate and htmllisttemplate config options. However, these
templates can also take data from extra columns in the maillist file
and use them in <output> elements.
- eg.
-
From our previous example, if the
listtemplate contains the following:
Hi <output name="maillist_2">, Email: <output name="maillist_1">
Then the email sent out to foo.bar@example.net would contain:
Hi Mr Foo, Email: foo.bar@example.net
the email sent out to fred.bloggs@example.com would contain:
Hi Bloggs, Fred, Email: fred.bloggs@example.com
and the email sent out to xyz@example.com would contain
Hi XYZ Man, Email: xyz@example.com
Email addresses and other column data is not shared between the email addresses
in the list. However, if your list is private, you should ensure it isn't
browsable from the internet.
Sometimes, you don't have your mailing list data in a file - to handle this, there
are two other sources of list information. It is possible to pull list information
from a form field using the listformfield config command to provide
the list data. The format of the list data provided by the form field should
be the same format as for the data file - ie. email as the first field, with
other fields separated by commas.
Even more useful, it is possible to pull mailing list information from a
SQL database by using the listsql command. This specifies a SQL statement
which returns a table, the first field of which should be an email address.
It is possible to attach files to emails sent out with a mailing list using
the listattachmentX and listattachmentXmime commands.
Other list config commands are: listsubject, listfrom and
listreplyto.
Pipelining Soupermail allows you to use Soupermail to process a form and then
send on the original information to another URL for processing. This is
useful if you want to use Soupermail as a logger, or as a quick email
function to another web application.
To use pipelining, you need to use the gotosuccess, gotoblank,
gotofailure and gotoexpires config commands. These commands
usually specify a URL to go to once Soupermail has finished, but they
can also be used dynamically by using variable replacement of
CGI VARIABLES.
- eg.
-
Once Soupermail's finished, I want to send the form onto a page
with the field foo set to the word bar. I can do this with the
following:
success: http://www.example.org/myscript?foo=bar
Now though, suppose I want to send whatever the user typed into one of
my form fields (eg. myfoofield). I can use the following:
success: "http://wwww.example.org/myscript?foo=${form_myfoofield}"
Some things to notice; The value of the config command has been wrapped in
double quotes - this allows CGI value replacement to happen.
The CGI value replacement is wrapped in { } braces - this makes it easier
to distinguish the value.
What about sending multiple values? Well, you can have things like:
foo=${form_myfoofield}&baz=${cookie_myBazCookie}
Here, foo is set to whatever value myfoofield was in the original
form, and baz is set to whatever value the cookie myBazCookie has. The
ampersand (&) character is used to separate the values.
For those of you who may be doing advanced pipelining, you should know that
URI escaping is only done to replaced values. So, this is wrong:
foo=my value&baz=${form_baz}
The space is illegal in URLs. It should be:
foo=my%20value&baz=${form_baz}
As from version 1.0.8, Soupermail has included support for database
access. It can be used to query, insert, amend and delete records in
a database. The commands used for this are:
sqlbindX
sqlname
sqlpassword
sqlrunX
sqluser
One important feature of Soupermail is the ability to use the values
returned by SQL SELECT statements in your config files and in templates.
All sqlrunX commands have an identifying number. All SQL commands
that return a table populate a two dimensional array of values. Used
in conjunction with the command number, it is possible to get
any return value from a SQL command.
- eg.
-
Lets say we have a table called 'test' containing these values:
| 1 | foo | boo |
| 2 | dish | dash |
| 3 | moo | maa |
Then, we have the following in our config:
sqlrun1: SELECT * FROM test
We can get values back from this by using the variable
sql_[command_number]_[row_number]_[col_number]. In config files,
this value should be prefixed with a $ sign.
In a config file:
if: "$sql_1_3_1" then subject: The test table has at least 3 rows
In a template:
The third field on the second row of the table test is:
<output name="sql_1_2_3"> = dash
To make use of database support with Soupermail, you'll need perl's DBI module
installed, and an appropriate DBD driver for your database. This driver must
support placeholders and bind values. Consult your DBD driver's manual
for more information on this.
From version 1.0.8, it is possible to store configuration files,
attachment files, templates and writable locations outside
your webserver's document tree. This is to allow you to store
information without it being viewable with a browser.
Not all ISP's will provide you with a directory outside your
document tree, so you may need to ask their support staff
for an appropriate location.
To call a config file in a private root, prefix the filename
with a '~' character when setting SoupermailConf.
- eg.
-
<input type="hidden" name="SoupermailConf" value="~/subscribe/sub.con">
Looks for a config file $privateRoot/subscribe/sub.con
One security restriction on private roots is that config files
outside the private root cannot read data from inside the config
root. ie. You can not have a config file outside the private
root calling a template inside the private root. The aim of this
is to save you if someone manages to write a config file on your
server. See the section on SECURITY for more information about
making Soupermail paranoid.
With the introduction of database support, Soupermail has become
a bit of a security headache for the consciencious webmaster. Here
are some tips about using Soupermail in a secure manner.
Firstly, NEVER put a database password and username in an unsecured
config file. If the config file can be read by a user with a web
browser, and the file contains database connection information, then
you are in trouble. Use the $privateRoot Soupermail has to put
your config files outside the webserver tree.
NEVER use a database user with high privileges (eg. sa, system, sys, root)
to access your database via Soupermail, unless you are in a very
trusted environment and you know exactly what will be going into
your SQL statements.
ALWAYS ensure you are using a good random password for your database
access - people's names and stuff are trivial to brute-force.
If you have a database with a network daemon, ALWAYS consider ways you
can restrict access to only known hosts.
ALWAYS use requires, length checking and type checking in config files
to make sure the data you pass to your SQL commands is valid.
NEVER make web writable directories in your CGI area.
ALWAYS consider how you will protect files written by Soupermail on
your webserver. Protecting the files usually involves ensuring that
they are safe from being read from a browser, the area being written
to cannot contain executables, that there is no means of anonymously
FTPing to the area and that other users on the system cannot exploit
the area.
ALWAYS remove backup files and temporary files from your live sites.
NEVER transmit credit card details by un-encrypted email.
NEVER store credit card numbers un-encrypted on your webspace.
Get to know the admin staff of your server space, or, at least find your
way around your service provider's support web pages. If they don't have
support web pages, then worry.
If your job is to maintain your website, make sure you've read
http://www.w3.org/Security/FAQ/. Website security is easily compromised
by misconfiguration of software - if you didn't read up about it, its
your fault.
Where possible, use secure communications to your webspace, rather than
insecure access (eg. SCP rather than FTP, SSH rather than Telnet,
encrypted pcAnywhere, etc). IMHO, this is simple common sense, but it
never hurts to say it again.
When you have Soupermail installed, you should be extra careful about
people being able to write config files to your system. If you are
using something like a message board, it may be possible for
someone to write a config file with it, and then use that config file
to read sensitive pages off your website. Beware!
To help counter this, from version 1.0.8, Soupermail will not read any
files from a directory containing a file called "soupermail.deny" (all
lower case). This file doesn't have to contain anything, just exist.
Place a soupermail.deny file in any directory that contains untrusted
content. Also place a soupermail.deny in any directory that contains
sensitive information (eg. ASP or PHP code containing database
logon details).
For even more security, you can set the $paranoid variable in Soupermail.
In this mode, Soupermail won't read any files from a directory, unless
the directory contains a file called "soupermail.allow". This is
the recommended approach for security conscious webmasters.
Soupermail requires perl 5.004 or better. See http://www.perl.com/ for where
to get perl from, or http://www.activestate.com/ if you need the Windows NT
version of Perl.
To handle the CGI input, Soupermail needs Lincoln D. Stein's excellent
CGI module, available from
http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
To do anything, Soupermail needs the MIME::Lite module installed on your
server. This module can be downloaded from CPAN.
http://www.cpan.org/modules/by-module/MIME/
To send email, Soupermail either needs a working Net::SMTP perl module
installed on the server, or, if you are on a UNIX server, a working
sendmail. Net::SMTP is distributed as part of the
Libnet set of packages available from CPAN. For users on Windows NT,
libnet is available with Activestate's Perl Package Manager.
On UNIX boxes, PGP requires PGP 2.6.3 or 5.0, available internationally from
http://www.pgpi.org/
Under NT, you can use the DOS version of PGP 5, again, available from
http://www.pgpi.org/. Unfortunately, I haven't got version 6.x to work
yet, so its the 16bit only.
GNU Privacy Guard is available from http://www.gnupg.org/
Some examples are distributed with Soupermail in
http://soupermail.sourceforge.net/downloads/examples.zip.
If anyone has any good sites with examples, please let me know.
Vittal Aithal <vittal.aithal@bigfoot.com>
I'd would be wrong to say I wrote this all on my own, other people made my life
difficult on the way, so I'd better credit them (only joking guys :)
A round of applause for everyone at
http://soupermail.sourceforge.net/credits.txt
Soupermail started life in late 1995 as a fairly lightweight CGI to handle
emails. However, as the years went by, it began to suffer heavily
from creeping featuritis, and has now grown into a monster. It started life
at Unipalm PIPEX, and various copies/versions are used by a number of
companies. UUNET UK ( http://www.uk.uu.net/ ) maintain a copy for their
WorldWeb service users, this copy escaped and worked at
Ionica. However, things went a bit pear-shaped, so now it teleworks
from my house or from Revolution ( http://www.revolutionltd.com/ ).
Success with PGP/GPG is highly variable upon platform its run on :( GPG
often depends on the Entropy Gathering Daemon to generate random numbers
and this may not work in a webserver user context.
CGIWrapped environments can prevent the config file location being passed in
with the PATH_INFO option, and will result in a config file error unless the
config location is passed in with the SoupermailConf form field.
Soupermail suffers from major bloat, but I just haven't worked up the will
to cull it down. The template code really needs to be modularised out.
Empty config files return a Thank you message, although nothing has happened.
Its debatable if this is correct.
|