NAME
mail_parser- direct incoming emails to customized perl handlers
SYNOPSIS
mail_parser [-v] [-m] [-f logfile] [-l library_path]
[-p pffile] [file [file...]]
SUPPORT
Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.
FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.
DESCRIPTION
Often it is convenient to have a variety of automatic email information and
request messages come into a single address for reformatting (info intake)
and data-distribution (info requests).
N.B. DISCLAIMER: All mail handling utilities in the Antelope contributed-code repository are provided as-is, with no guarantee either express or implied that they will function as desired, as described, or as expected. All risk of loss or difficulty of any sort from running these utilites is assumed solely by the end user.
mail_parser takes a mail file composed of one or more messages, parses the
input into component messages, and searches its parameter file for perl-script
handlers that apply to the given sender and subject. If no handler is found,
the message is ignored. Otherwise the message is handed to the first handler
that applies and the rest of the handlers are skipped for that message. The
mail_parser parameter file specifies perl regular expressions which the
email sender and subject must match in order for the handler to be used on it.
If no filename or filenames are specified on the command line, mail_parser
expects to receive input from standard-in.
When multiple mail-messages are stored in files, embedded lines in each
message that start with "From " are escaped with a '>' character. When
mail messages are delivered into a .forward file, these escape-characters
are removed. Therefore mail-parser requires a command-line switch to
toggle between two different modes. The '-m' switch allows the input
to be parsed into multiple messages if multiple messages are present. This
mode assumes that embedded From lines are properly escaped. The -m option
is recommended when reading from a file. In the mode without -m, mail_parser
assumes that only one message is being fed to it. Embedded From lines
are ignored. This mode (without -m) is recommended when mail_parser is
being fed directly from a mail utility, for example via a .forward file.
The parameter file entries for individual handlers may contain parameters
specific to each handler, in addition to the required sender and subject
regular expressions.
If a mail message is found for which a given handler applies, mail_parser loads
the handler and runs it. This is most easily shown with an example. If a mail
message comes in for which the "submit_pepp" handler applies, mail_parser first
attempts to load submit_pepp.pl with the perl "require" command. After doing
this, mail_parser expects it will have available to it the perl subroutine
submit_pepp_handler(). This subroutine should take two arguments: the first is
an object reference to a Perl Mail::Internet object. The second is a Perl
reference to a hash. This hash contains the associative-array entries for the
submit_pepp handler from the mail_parser.pf parameter file.
Installing mail_parser to handle mail for a given email account usually
requires the
mail_parser_wrapper(1) script also, which is documented
separately.
OPTIONS
-
-v
verbose output
-
-l lib_dir
Specify library directory with *.pl files containing handlers.
Note that if handlers are contained in the standard $(ANTELOPE)/data/perl
directory this should not be necessary.
-
-p pffile
Specify the parameter file. Default is mail_parser.pf
-
-f logfile
Specify a file for log messages and program output
-
-m
Enable splitting of the input file(s) into multiple mail messages
PARAMETER FILE
The mail_parser parameter file contains an ordered table of associative
arrays. Each handler will have an associative array containing at least
three key-value pairs: one for subject, one for sender, and one for handler
name. The first two are Perl regular-expressions specifying the mail-messages
for which the handler should be applied. The third is the name of the handler
itself. Handlers will be tested against incoming mail messages in the order
in which the handlers appear in this table. The example shown here is
for the submit_pepp handler. For further details on this handler, please
see the submit_pepp(3) man page.
Handlers &Tbl{
&Arr{
handler submit_pepp
sender rphinney@Princeton.EDU
subject PEPP Earthquake Alert
site_db /Seis/databases/stations/master_stations
waveform_db /iwrun/op/db/archive/archive_%Y_%m_%d
net PP
pre_P_sec 480
post_P_sec 1200
filetime %Y_%m_%d_%H:%M
wffilename %{sta}_FILETIME.%{chan}.sac
wfformat sc
ftp_repository giseis.alaska.edu
ftp_dir pub/USERS/kent
ftp_user anonymous
ftp_password kent@giseis.alaska.edu
ftp_timeout 60
}
}
EXAMPLE
% mail_parser -v -p check pepp_mail
Event 1 1 9/30/2000 19:05:07.000 57.5700 -142.9700 33.0000 -999.00
GCSA BHE 9/30/2000 18:59:25.340 28:00 minutes 84000 50.0000000 0 sc
GCSA BHN 9/30/2000 18:59:25.340 28:00 minutes 84000 50.0000000 0 sc
GCSA BHZ 9/30/2000 18:59:25.340 28:00 minutes 84000 50.0000000 0 sc
NHSA BHZ 9/30/2000 18:58:19.900 28:00 minutes 33600 20.0000000 0 sc
PPSA BHZ 9/30/2000 18:58:26.250 28:00 minutes 33600 20.0000000 0 sc
Connected to lasker.princeton.edu.
220 lasker.Princeton.EDU FTP server (SunOS 5.7) ready.
Name (lasker.princeton.edu:kent): school
331 Password required for school.
Password:
230 User school logged in.
ftp> cd .
250 CWD command successful.
ftp> binary
200 Type set to I.
ftp> put GCSA_2000_09_30_19:05.BHE.sac
200 PORT command successful.
150 Binary data connection for GCSA_2000_09_30_19:05.BHE.sac (137.229.32.109,33758).
226 Transfer complete.
local: GCSA_2000_09_30_19:05.BHE.sac remote: GCSA_2000_09_30_19:05.BHE.sac
336632 bytes sent in 2.2 seconds (150.49 Kbytes/s)
ftp> put GCSA_2000_09_30_19:05.BHN.sac
200 PORT command successful.
150 Binary data connection for GCSA_2000_09_30_19:05.BHN.sac (137.229.32.109,33760).
226 Transfer complete.
local: GCSA_2000_09_30_19:05.BHN.sac remote: GCSA_2000_09_30_19:05.BHN.sac
336632 bytes sent in 2.2 seconds (152.63 Kbytes/s)
ftp> put GCSA_2000_09_30_19:05.BHZ.sac
200 PORT command successful.
150 Binary data connection for GCSA_2000_09_30_19:05.BHZ.sac (137.229.32.109,33761).
226 Transfer complete.
local: GCSA_2000_09_30_19:05.BHZ.sac remote: GCSA_2000_09_30_19:05.BHZ.sac
336632 bytes sent in 2.1 seconds (158.05 Kbytes/s)
ftp> put NHSA_2000_09_30_19:05.BHZ.sac
200 PORT command successful.
150 Binary data connection for NHSA_2000_09_30_19:05.BHZ.sac (137.229.32.109,33762).
226 Transfer complete.
local: NHSA_2000_09_30_19:05.BHZ.sac remote: NHSA_2000_09_30_19:05.BHZ.sac
135032 bytes sent in 1.1 seconds (124.21 Kbytes/s)
ftp> put PPSA_2000_09_30_19:05.BHZ.sac
200 PORT command successful.
150 Binary data connection for PPSA_2000_09_30_19:05.BHZ.sac (137.229.32.109,33763).
226 Transfer complete.
local: PPSA_2000_09_30_19:05.BHZ.sac remote: PPSA_2000_09_30_19:05.BHZ.sac
135032 bytes sent in 1.2 seconds (113.40 Kbytes/s)
ftp> quit
%
DIAGNOSTICS
BEGIN: 10/12/2000 8:04:35.133 UTC
No handler for
Subject:
From: kent@giseis.alaska.edu (Kent Lindquist (Seismologist))
END
Security restriction: ANTELOPE environment variable must
match ^/opt/antelope. Bye.
Security problem with handler name $handler
Couldn't find Handlers table in parameter file $Pf (is $Pf accessible??)
SEE ALSO
mail_parser_wrapper(1), submit_pepp(3), pf(5), perl(1),
sendmail(1), aliases(4), autodrm(1), autodrm_wrapper(1)
BUGS AND CAVEATS
mail_parser was originally written with Perl taint-checking turned on. Because
some of the handlers commit tasks (file writing etc.) that do not
pass Perl taint-checking, taint-checking has been turned off in the mail_parser
script. However it is good to keep security in mind when writing individual
handlers. If handler content permits it, the operator may want to turn
taint-checking back on.
parameters passed to individual handlers via the mail_parser.pf parameter
file will be affected by the standard parameter-file parsing. For
example, characters such as the pound character must be escaped with a
backslash.
sendmail security may affect the installation of this command to automatically
process incoming mail. For details, see your system administrator.
mail_parser is written so that if something goes wrong, it will report the error
but still die with exit status of zero. This prevents mail_parser problems
from causing the input email to bounce back to the sender, i.e. automatically
airing dirty laundry in public. The price of this feature is that any eval
commands in handlers must be replaced by calls to myeval(), or alternatively
the author needs more hints about perl.
Two options would be nice to have: logging of incoming email messages, and
an option to specify forwarding addresses in the mail_parser parameter file.
The former at least is straightforward. Both of these goals may be accomplished
through appropriate setup of the .forward file. The advantage of parameter-file
specification of forwarding addresses is that the choice of forwarding
recipients could be tailored to the filtering on sender/subject. Initial
experiments with the Mail::Internet->smtpsend() were left aside in the
interests of getting real work done.
AUTHOR
Kent Lindquist
Geophysical Institute
University of Alaska, Fairbanks
Antelope User Group Contributed Software